MCP Facebook Ads

MCP脸书广告

MCP服务器用于查询Facebook广告API（营销API）的数据 只读.

🚀 功能

• ✅ 查询活动
• ✅ 获取活动指标和表现
• ✅ 提取账户见解和报告
• ✅ 查询广告创意

📋 先决条件

• Node.js 18及以上版本
• 在（某处/某时间）创建的Facebook应用 Facebook 开发者
• 具有读取权限的访问令牌ads_read)
• 广告账户的账户ID

🔧 安装

1. 克隆仓库：

cd mcp-facebook-ads

1. 安装依赖项：

npm install

1. 配置环境变量：

cp .env.example .env

1. 编辑文件 .env 带着他的凭证：

FB_ACCESS_TOKEN=seu_token_aqui
FB_ACCOUNT_ID=seu_account_id_aqui
FB_API_VERSION=v21.0

1. 构建项目：

npm run build

🎯 如何使用

选项1：通过npx（推荐）

将其添加到您的MCP配置文件中（例如： .cursor/mcp.json):

"facebook-ads": {
  "command": "npx",
  "args": [
    "--yes",
    "mcp-facebook-ads",
    "--transport",
    "stdio"
  ],
  "env": {
    "FB_ACCESS_TOKEN": "seu_token_aqui",
    "FB_ACCOUNT_ID": "seu_account_id_aqui",
    "FB_API_VERSION": "v21.0"
  }
}

选项2：本地运行

npm start

🛠️ 可用的工具

1. get_campaigns

返回广告账户的广告系列列表。

参数：

• fields (可选)：要返回的字段（例如： id,name,status,objective)
• limit （可选）：结果限制（默认：25）

2. get_campaign_insights

返回特定活动的指标和性能数据。

参数：

• campaign_id （必填）：活动ID
• date_preset (可选)：预定义时间段（例如： last_7d， last_30d， lifetime)
• since （可选）：开始日期，格式为 YYYY-MM-DD（需要 until)
• until (可选)：以 YYYY-MM-DD 格式填写结束日期（需 since）
• fields （可选）：要返回的指标（例如： impressions,clicks,spend,ctr)

注： 使用 date_preset 或者 since/until 以确定时间段。如果两者都提供， since/until 将享有优先权。

3. get_account_insights

返回广告账户的见解和报告。

参数：

• date_preset (可选)：预定义时间段（例如： last_7d， last_30d， today)
• since (可选)：起始日期格式为 YYYY-MM-DD（需要 until)
• until (可选)：结束日期，格式为YYYY-MM-DD（需 since）
• fields (可选)：要返回的指标（例如： impressions,clicks,spend,cpc,cpm,ctr）
• level （可选）：聚合级别（account， campaign， adset， ad)

注： 使用 date_preset 或者 since/until 以定义时间段。如果两者都提供了， since/until 将享有优先权。

4. get_ad_creatives

返回有关广告创意的信息。

参数：

• ad_id （必填）：广告ID
• fields （可选）：要返回的字段（例如： name,thumbnail_url,object_story_spec)

📚 API的有用字段

活动：

• id， name， status， objective， daily_budget， lifetime_budget， created_time

指标/见解：

• impressions， clicks， spend， ctr， cpc， cpm， reach， frequency， conversions

创意人员：

• id， name， thumbnail_url， image_url， video_id， object_story_spec

🔐 获取访问令牌

1. 访问 Facebook 图形API浏览器
2. 选择您的应用程序
3. 添加权限： ads_read
4. 点击“生成访问令牌”
5. 复制生成的令牌

⚠️ 重要提示： 短期令牌在1-2小时内过期。如需长期使用，请生成一个 长期有效的令牌（或持久令牌）。

📖 API文档

• 脸书营销API
• 图API浏览器
• 见解API

📝 许可证

麻省理工学院（MIT）