Meta Ads

影片展示的是使用示例数据的托管版 getmcpads。其中的 MCP Apps 功能，从创意图库和提醒到 Google Sheets 导出和批量发布，都属于托管产品。本仓库提供独立的原生 API 工具。

42 个读取工具 · 24 个写入工具，默认禁用。

使用你自己的平台凭据，以及支持 stdio MCP 的客户端（例如 Claude Desktop、Claude Code 或 Cursor）在本地运行。请求将直接发送到平台。如需托管连接（包括受支持的 ChatGPT 配置），请使用托管选项。

更新内容

v2.1.1：Zod 4 安全更新 · 2026 年 10 月 26 日

• 将 zod 更新至 4.6.7。所有早于 4.6.6 的 Zod 版本都受到高危安全公告 GHSA-mrhx-c7xc-m3w5 的影响：验证超大且带约束的集合可能耗尽内存，而且没有任何 Zod 3 版本包含此修复。npm audit --omit=dev 再次显示无漏洞。
• 保持 Zod 3 的验证行为。参数默认值在使用前仍会经过验证和补全，因此省略对象时仍须提供其必填字段。
• 参数为可选或设有默认值时，保留其自身描述。Zod 4 只会将描述存储在包装后的 schema 上，否则共享的回退描述可能会取而代之。
• 通过 MCP 发布的工具名称、参数和描述均未改变。使用 Zod 4 的 JSON Schema 输出重新生成了 server-card.json，其中部分约束的表述有所不同。

此前的版本

版本	日期	主要更新
2.1.0	2026 年 10 月 23 日	网关同步和运行时安全更新
2.0.1	2026 年 9 月 23 日	恢复公开仓库
2.0.0	2026 年 9 月 20 日	网关同步和安全修复
1.1.0	2026 年 9 月 13 日	平台能力同步和质量契约
1.0.2	2026 年 8 月 30 日	通过 MCP 公布软件包版本。
1.0.1	2026 年 8 月 30 日	为官方 MCP Registry 添加 server.json 和 mcpName，名称为 com.getmcpads/meta-ads。
1.0.0	2026 年 8 月 29 日	首次开源发布

完整更新日志 · 所有版本

源同步：SOURCE_SYNC.md。

升级说明

需要 22 系列的 Node.js 22.23.4 或更高版本、24 系列的 24.22.1 或更高版本，或 26.12.1 或更高版本。这些版本包含 2026 年 10 月的安全修复。在较旧的运行时上，服务仍会启动，并向 stderr 写入警告。CI 覆盖 Node 22、24 和 26。meta_health_check 现在会将无法运行的检查报告为未知，而不是缺失。重新使用已保存的参数前，请先阅读当前工具架构。写入仍为可选操作，且需要明确确认。托管创意集成和 MCP Apps UI 不在此版本范围内。

安装此版本

这是一个 GitHub 源码版本。npm 和 MCP Registry 版本会单独发布。以下命令会选择此确切版本；本文后面的未固定版本 npx 示例会选择 npm 上当前可用的版本。

git clone --branch v2.1.1 --depth 1 https://github.com/get-mcp-ads/meta-ads-mcp-server.git
cd meta-ads-mcp-server
npm ci
npm run build

配置 MCP 客户端，使其使用 node 运行 dist/cli.js 的绝对路径，并提供下文所述的平台凭据。

更倾向于托管连接？ 通过托管服务 getmcpads 使用 Meta Ads。连接你的账户，选择助手可访问的数据，并使用托管 MCP 连接。当前功能和方案请参阅网站。

你将获得

42 个读取工具	广告系列、广告组、广告、创意、受众、像素、目录、主页、Instagram、活动日志、A/B 测试和提升研究
24 个写入工具	默认关闭。状态、预算、排期、重命名、创建广告系列。每项操作都会先预览，再应用
190 个指标	包括在客户端计算的衍生指标（ROAS、CPA、频次、开场率、归因窗口浏览量）
56 个细分维度 · 90 个维度	配备兼容性矩阵，可在无效组合触达 API 之前识别出来
7 个资源	模型可读取的实时目录：指标、细分维度、兼容性规则、11 个工作流配方
向前兼容的读取	meta_get_node_fields、meta_list_edge_raw、meta_get_insights_raw 可访问此服务尚未建模的 Graph 字段

查询规划器

Meta 会拒绝许多指标与细分维度的组合，而且错误消息很少说明原因。 此服务对兼容性矩阵进行了编码，因此会将不可能的请求拆分为多个有效的 API 调用并合并结果，而不是直接失败。

meta_validate_query 可让模型在消耗一次调用之前检查组合。 这就是只会报告“API 返回错误 100”的助手与能返回你的数据的助手之间的区别。

---

获取令牌

这是唯一需要花费实际精力的步骤，而且值得认真完成。

你需要一个带有 ads_read 权限的 Meta 访问令牌。有三种获取方式；我们推荐第二种。

推荐：系统用户令牌（不会过期）

系统用户属于你的 Business，而不是某个人。其令牌不会因密码更改或员工离职而失效，并且访问你的 Business 已拥有的广告账户无需应用审核。

1. 前往 Business 设置 → 用户 → 系统用户
2. 点击添加系统用户。除非有更多权限需求，否则赋予其员工角色。
3. 分配资产 → 选择你的广告账户 → 授予查看成效权限（仅当你计划启用写入时，才添加管理广告系列权限）。
4. 生成新令牌 → 选择你的应用 → 选择权限范围 ads_read（仅在写入时添加 ads_management）。
5. 将有效期设为永不过期。
6. 复制令牌。Meta 只会显示一次。

📖 Meta 的系统用户文档

快速测试：Graph API Explorer（约 1 小时后过期）

适合试用此服务，不适合日常工作。 Graph API Explorer → 选择你的应用 → 添加 ads_read → 生成访问令牌。

长期用户令牌（约 60 天）

将短期令牌换成有效期为 60 天的令牌。每两个月需要重新操作一次。 📖 长期令牌

需要哪些权限？

权限	何时需要
ads_read	始终需要。 广告系列、成效分析等所有只读操作
ads_management	仅在将 META_ENABLE_WRITES=1 时需要
business_management	可选。发现 Business Manager 资产
pages_show_list, pages_read_engagement	可选。主页帖子和自然流量补充信息
instagram_basic	可选。已关联的 Instagram 账户
catalog_management	可选。读取产品目录

首次调用时运行 meta_health_check：它会报告你实际拥有的权限范围，以及你尝试使用的工具所缺少的权限范围，且不会打印你的令牌。

---

设置

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS） 或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": ["-y", "@getmcpads/meta-ads-mcp-server"],
      "env": {
        "META_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

重启 Claude Desktop。向它询问：“列出我的 Meta 广告账户”。

Claude Code

claude mcp add meta-ads --env META_ACCESS_TOKEN=your-token-here -- npx -y @getmcpads/meta-ads-mcp-server

Cursor

在你的项目中创建 .cursor/mcp.json，格式与上面的 Claude Desktop 配置相同。

从源代码安装

git clone https://github.com/get-mcp-ads/meta-ads-mcp-server.git
cd meta-ads-mcp-server
npm install && npm run build
cp .env.example .env   # then fill in META_ACCESS_TOKEN
npm start

配置

变量	默认值	含义
META_ACCESS_TOKEN	无	必需。 你的 Meta 访问令牌
META_ENABLE_WRITES	未设置	设置为 1 以注册 24 个写入工具
META_API_VERSION	v26.0	Graph API 版本。可覆盖此值以固定使用其他版本
LOG_LEVEL	info	debug、info、warn、error

随时检查你的设置：

npm run doctor

---

写入操作，以及为何要先预览

默认情况下，写入工具处于禁用状态。设置 META_ENABLE_WRITES=1 即可启用。

启用后，每个写入工具都会返回预览，且不会进行任何更改：

// meta_update_adset_budget { adSetId: "123", currency: "EUR", dailyBudget: 50 }
{
  "applied": false,
  "action": "meta_update_adset_budget",
  "change": { "adSet": "123", "field": "daily_budget", "amount": 50,
              "currency": "EUR", "inMinorUnits": 5000 },
  "message": "Preview only, nothing was changed. Repeat the same call with confirm: true to apply this change to the live account."
}

只有在第二次调用中传入 confirm: true，才会修改线上账户。

这是有意为之。助手会组合这些调用，但可能会选错账户、选错广告系列，或把预算数量级搞错。强制预览可以让错误在造成金钱损失之前显现出来，并为人类提供一个停止操作的机会，而协议本身并不保证这一点。

另外还有两项保护措施：

• meta_create_campaign 始终会创建状态为 PAUSED 的广告系列。 无法选择创建后立即启用。
• 预算会按币种转换为最小单位。 日元、韩元和中非法郎没有更小单位，因此为 ¥12.50 发送 1250 会使支出扩大 100 倍。服务会识别这些无小数位币种。

工具	更改内容
meta_update_campaign_status / _adset_status / _ad_status	暂停或重新启用
meta_update_campaign_budget / _adset_budget	日预算或总预算
meta_update_adset_schedule	开始和结束时间
meta_rename_campaign / _adset / _ad / _ad_account	仅名称
meta_create_campaign	创建广告系列，状态始终为 PAUSED

---

工具

下方列出了所有工具。完整的参数和输出架构请参阅 server-card.json。

42 个读取工具

| 工具 | 用途 | | --- | --- | | `meta_health_check` | 只读连接诊断：检查令牌身份和已授予的权限，并列出可访问的广告账户，不会暴露访问令牌。 | | `meta_get_business_assets` | 只读发现可访问的 Meta Business 资产：在权限允许时，获取企业、主页、Instagram 账户、像素和数据集。 | | `meta_get_pages` | 列出可访问的 Facebook 主页，包含 ID、名称、类别、任务、图片，以及可用时关联的 Instagram 账户引用。 | | `meta_get_instagram_accounts` | 在权限允许时，列出关联到可访问主页、Business Manager 资产或广告账户的 Instagram 账户。 | | `meta_get_pixels` | 在可访问时，列出广告账户或 Business Manager 中的像素和数据集；对于权限受限的边，返回可操作的警告。 | | `meta_get_ad_activity` | 从 `/{ad_account_id}/activities` 读取广告账户活动日志，包含对象、事件、执行者、时间戳和 extra_data 字段。 | | `meta_get_delivery_diagnostics` | 使用可用的 status/effective_status/issues_info 和简单的投放洞察，对广告系列、广告组和广告进行只读投放诊断汇总。 | | `meta_get_creative_assets` | 返回关联广告的创意媒体，包含实际广告名称、合集封面、所有轮播/灵活格式组件、解析后的图片哈希和视频 URL。 | | `meta_get_audience_details` | 在权限允许时，分页读取详细的自定义、已保存和类似受众，并返回丰富字段。 | | `meta_get_catalog_products` | 在可访问商品目录时，读取商品目录和商品项目。 | | `meta_join_product_insights` | 查询按商品细分的洞察，并在可访问商品目录时使用商品目录元数据丰富结果行。 | | `meta_get_brand_safety_controls` | 从广告账户/广告组定向和可选的屏蔽名单边中读取品牌安全、品牌适宜性、版位和上下文控制信号。 | | `meta_interpret_experiment_results` | 读取并解读 A/B 测试或转化提升研究结果，提供置信度保护措施、分组、目标以及可选的分组实体。 | | `meta_get_organic_content_enrichment` | 读取 Facebook 主页帖子和 Instagram 媒体，包含 URL、原生周期和可选洞察。 | | `meta_list_ad_accounts` | 列出当前令牌可访问的所有 Meta 广告账户。 | | `meta_get_account_details` | 获取特定 Meta 广告账户的详细信息：名称、货币、时区、支出上限、状态和企业信息。 | | `meta_get_campaigns` | 列出 Meta 广告账户的广告系列。 | | `meta_get_adsets` | 列出 Meta 广告账户的广告组，可按广告系列筛选。 | | `meta_get_ads` | 列出 Meta 广告账户的广告，可按广告组筛选。 | | `meta_get_insights` | 查询 Meta Ads 效果洞察。 | | `meta_get_campaign_structure` | 获取分层广告系列结构：广告系列 -> 广告组 -> 广告。 | | `meta_get_creatives` | 获取广告创意内容：文本、图片、视频、链接和行动号召。 | | `meta_get_audiences` | 列出 Meta 广告账户的自定义、已保存和类似受众。 | | `meta_get_ad_studies` | 列出广告账户的转化提升研究和 A/B 测试（Ad Studies）。 | | `meta_get_study_results` | 获取转化提升研究或 A/B 测试的详细结果。 | | `meta_validate_query` | 执行前验证指标/细分组合。 | | `meta_get_page_posts` | 使用从已连接用户解析的主页令牌，读取已发布的 Facebook 主页帖子。 | | `meta_debug_token` | 检查令牌身份、有效性、到期时间和权限范围。 | | `meta_search_entities` | 在广告账户内按名称搜索广告系列、广告组或广告。 | | `meta_get_node_fields` | 从单个 Meta Graph 节点读取任意扁平字段。 | | `meta_list_edge_raw` | 列出允许访问的只读 Meta Graph 边，支持调用方选择扁平字段、筛选条件和游标分页。 | | `meta_get_insights_raw` | 查询 Meta Insights 边，支持经过验证的原生字段名称、细分、操作细分、归因窗口、筛选条件、排序、汇总和分页。 | | `meta_search_targeting_options` | 搜索 Meta 的只读定向元数据，包括兴趣、已验证兴趣、地理位置、语言区域、国家、城市、地区、市场或邮政编码。 | | `meta_get_ad_preview` | 获取现有 Meta 广告在指定版位格式下的只读预览标记。 | | `meta_list_ad_images` | 列出广告账户图片库（/adimages）：哈希、名称、尺寸、状态、永久公开展示 URL（permalink_url）、短期 CDN URL，以及可选的使用各图片的创意。 | | `meta_list_ad_videos` | 列出广告账户视频库（/advideos）：标题、时长、处理状态，以及公开提供的缩略图（首选尺寸和最大尺寸）。 | | `meta_get_video_sources` | 为指定广告视频解析新的下载 URL（source）和缩略图。 | | `meta_get_entity_configuration` | 读取广告账户中的特定实体，以进行核对。 | | `meta_get_uploaded_video` | 检查视频处理状态以及它是否属于所选账户的视频库。 | | `meta_get_adset_configuration` | 读取现有广告组、其上级广告系列预算/目标，以及账户货币，以便准备编辑或添加广告。 | | `meta_get_promotable_apps` | 列出此广告账户可推广的应用及其商店 URL，以便设置网站和应用（跨渠道）广告组。 | | `meta_get_catalog_batch_status` | 读取商品目录批次句柄的完成状态和各项目错误。 |

24 个写入工具

默认禁用。除非明确确认，否则调用只会预览。使用前请检查配置和确切的 schema。

工具	用途
meta_create_campaign	创建一个已暂停的 Meta 广告系列，可使用广告组预算（省略广告系列预算）、每日广告系列预算或总预算。
meta_update_adset_budget	检查上级预算和现有排期后，更改广告组的每日预算或总预算。
meta_update_adset_schedule	使用带有明确时区偏移的 ISO 8601 格式，更改开始时间和/或结束时间。
meta_update_campaign_budget	验证币种和所有权后，更改现有的广告系列自有预算。
meta_create_adset	创建一个已暂停的 Meta 广告组，并明确指定定向、优化、版位、归因、竞价和排期。
meta_update_adset_configuration	更新定向、优化、版位、归因、竞价、预算或排期。
meta_duplicate_adset	在所选账户中复制一个已验证效果良好的广告组，并保留复杂的原生配置。
meta_create_adcreative	使用现有帖子，或明确指定 object_story_spec 和可选的 asset_feed_spec，创建广告创意。
meta_create_ad	使用所选账户中现有的广告组和广告创意创建一个已暂停的广告。
meta_update_ad_creative	将广告创意替换为同一账户中的另一个现有广告创意。
meta_upload_ad_image	使用 Base64 字节将图片上传到所选广告账户（解码后最多 5 MiB）。
meta_upload_ad_video	从可公开访问的 HTTPS URL 或 Base64 MP4 字节导入视频（解码后最多 5 MiB）。
meta_create_custom_audience	创建网站受众、互动受众、客户名单受众容器或类似受众。
meta_update_custom_audience	更新现有自定义受众的名称、描述、保留期限或完整规则。
meta_create_product_set	在与所选广告账户归属同一 Business 的目录中创建经过筛选的商品集。
meta_update_product_set	替换商品集筛选条件或重命名商品集。
meta_batch_catalog_items	通过 retailer_id 创建或更新最多 50 件目录商品。
meta_update_campaign_status	暂停或重新启用 Meta 广告系列。
meta_update_adset_status	暂停或重新启用 Meta 广告组。
meta_update_ad_status	暂停或重新启用 Meta 广告。
meta_rename_campaign	重命名 Meta 广告系列。
meta_rename_adset	重命名 Meta 广告组。
meta_rename_ad	重命名 Meta 广告。
meta_rename_ad_account	重命名 Meta 广告账户。

7 个资源

URI	内容
meta://manifest	此服务提供的内容，以及应首先运行的工具
meta://metrics	全部 190 项指标及其类别和格式
meta://breakdowns	全部 56 项细分维度及其适用范围
meta://compatibility	兼容性矩阵，共 90 个维度
meta://recipes	11 个分步工作流
meta://p2-readonly	只读权限范围说明
meta://app-review	Meta App Review 提交的权限范围说明

---

安全

此服务持有一项凭证，可读取实时广告账户，并在启用写入功能时修改这些账户。 具体而言：

• 不会在任何日志级别记录令牌，也不会将其写入磁盘。
• 请求只会发送到固定版本的 graph.facebook.com。其他任何主机都会被拒绝，不会发起调用。已通过测试验证。
• 附加令牌后会拒绝重定向，因此重定向无法将你的凭证转发到其他位置。已通过测试验证。
• **无遥测。**除 Graph API 外，此服务不会发起任何网络调用。它不包含分析功能、不会向外发送数据，也不会报告使用情况。你可以通过搜索源代码中的 fetch 验证这一点。

完整政策和报告说明：SECURITY.md。

---

正在寻找托管式、多平台版本？

如果你想使用此数据源，但不想运行本地服务，可以试用托管版 Meta Ads。 getmcpads 还可通过一个 MCP URL 连接广告、Search Console 和 GA4。 数据源可用情况和套餐限制请见网站；仍需连接账户。

1. 按照 Meta Ads 连接指南操作。
2. 选择助手可以读取的账户或媒体资源。
3. 连接 Claude、 ChatGPT 或 Codex。
4. 尝试进行只读审查：“比较广告系列结果，并结合 CTR 调查频次。指出缺失的数据，不要进行任何更改。”

在选择付费套餐前，请查看当前托管工具目录 和定价。 这个 Apache 2.0 适配器仍可使用你自己的凭据独立运行。

---

参与贡献

欢迎提交问题和拉取请求。请参阅 CONTRIBUTING.md。 报告任何与安全相关的问题前，请阅读 SECURITY.md。

许可证

Apache License 2.0。另请参阅 NOTICE。

Facebook、Meta、Instagram 和 Meta Marketing API 均为 Meta Platforms, Inc. 的商标。 本项目与 Meta Platforms, Inc. 无关联，未获其认可或赞助。 这是一个独立的公共 API 客户端。

MCP 合约和桌面应用套件

每个工具都声明了读写注解、参数说明和结构化输出架构。成功调用会将有效负载置于 structuredContent.result；错误会保留 isError: true。生成的服务卡仅包含定义。

运行 npm run bundle -- /path/to/output，即可根据当前目录构建 .mcpb 桌面应用套件。安装期间在本地输入凭据。除非明确启用，否则写入工具会保持禁用状态。

更多 getmcpads 项目

Google Ads · Google Analytics 4 · Google Search Console · TikTok Ads · Pinterest Ads · X Ads

由 getmcpads 的 Emmanuel 维护。问题请联系：[email protected]。