X Ads

短片展示的是使用示例数据的托管版 getmcpads。其 MCP Apps 功能涵盖创意素材库、提醒、Google Sheets 导出和批量启动等，属于托管产品。此代码库提供独立的原生 API 工具。

25 个读取工具 · 21 个写入工具，默认禁用。

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

更新内容

v1.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 只会在包装后的架构上存储描述，否则共享的回退描述可能会覆盖它。
• 通过 MCP 发布的工具名称、参数和描述保持不变。server-card.json 已使用 Zod 4 的 JSON Schema 输出重新生成，其中某些约束的表达方式有所不同。

更早的版本

版本	日期	主要更新
1.1.0	2026 年 10 月 23 日	重命名广告系列和广告组
1.0.1	2026 年 9 月 23 日	恢复公开代码库
1.0.0	2026 年 9 月 20 日	首次独立发布

完整更新日志 · 所有版本

源同步信息：SOURCE_SYNC.md。

升级说明

需要 Node.js 22.23.4、24.22.1、26.12.1 或更高版本。这些版本包含 2026 年 10 月的安全修复，在较旧版本上运行时，服务会向 stderr 输出警告。CI 覆盖 Node 22、24 和 26。

没有破坏性变更。 配置变量和接受的值均未更改：X_ADS_ACCOUNT_IDS 仍为必填项，且与 1.0 一样，只有值为 true 才会启用写入。重命名工具属于写入操作：只有设置 X_ADS_ENABLE_WRITES=true 时才会显示，并且需要在 X_ADS_SCOPES 中包含 ads.write。

重新使用已保存的参数前，请先查看当前工具架构。写入仍为可选操作，且需要明确确认。本次发布不包含托管式创意集成和 MCP Apps UI。

安装此版本

这是一个 GitHub 源码版本。npm 和 MCP Registry 版本会单独发布。以下命令会选择此确切版本。

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

配置 MCP 客户端，使其运行 node，并将 dist/cli.js 的绝对路径作为参数；平台凭据请参阅下文。

更喜欢托管连接？ 通过托管服务 getmcpads 使用 X Ads。连接账户，选择助手可以访问的数据，然后使用托管 MCP 连接。当前功能和方案请参阅网站。

配置

通过客户端的机密配置提供以下环境变量：

变量	用途
X_ADS_ACCESS_TOKEN	用户的 OAuth 2.0 访问令牌。仅应用的 bearer 令牌不够用。
X_ADS_ACCOUNT_IDS	必填的逗号分隔账户 ID，且仅限令牌可访问的账户。
X_ADS_SCOPES	实际授予令牌的权限范围。默认为 ads.read。
X_ADS_ENABLE_WRITES	默认为 false。只有精确值 true 才会开放写入操作。

请参阅 X 官方设置指南获取令牌并申请 Ads Project 访问权限。 报表使用 ads.read，修改广告系列使用 ads.write，上传和写入媒体库使用 media.write。 设置 X_ADS_SCOPES 并不会授予权限。此软件包接受令牌，但不会运行 OAuth 浏览器流程，也不会保存轮换刷新令牌。令牌过期时，请安全地续期并重启服务。

安全与覆盖范围

写入操作默认会先预览。再次调用并设置 confirm: true 前，请检查确切的账户、目标和参数。 广告系列和广告组会以暂停状态创建。启用它们可能会产生广告费用。媒体上传最多为 4 MB，并可能消耗 X API 点数。 如果写入结果不确定，请勿自动重试。先读取账户信息并核对状态。 调用分发前会检查所选账户，并过滤账户发现响应。未知参数会被拒绝。 保留原生分页、归因和金额 _micro 字段。一个微单位为账户货币的百万分之一。

此服务仅开放官方 API 中经过审核的子集，不会自动开放上游新增的工具。 已包含原生媒体读取和写入。不包含托管式创意库、可视化编辑器和 MCP Apps UI。 确切架构请使用 tools/list 或查看 server-card.json，提供方详情请参阅官方 API 参考。

托管选项

getmcpads for X Ads 管理托管连接和账户选择。 托管版本与源码版本可能有所不同。联系方式：[email protected]。

开发

npm run typecheck
npm run lint
npm run build
npm test
npm run catalog

所有测试均使用合成响应离线运行，不会更改任何真实账户。

工具

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

25 个读取工具

| 工具 | 用途 | | --- | --- | | `x_ads_list_ads_accounts` | 列出已通过身份验证的用户可访问的广告账户 | | `x_ads_list_campaigns` | 列出某个账户的广告系列 | | `x_ads_get_campaign` | 按 ID 获取单个广告系列 | | `x_ads_list_funding_instruments` | 列出广告账户的资金来源（付款来源） | | `x_ads_list_line_items` | 列出广告账户的广告组 | | `x_ads_get_line_item` | 按 ID 获取单个广告组 | | `x_ads_list_promoted_posts` | 列出广告账户的推广帖子（推广推文） | | `x_ads_list_targeting_criteria` | 列出广告账户广告组的定向条件 | | `x_ads_list_account_posts` | 列出广告账户可用于推广的帖子（推文） | | `x_ads_list_web_event_tags` | 列出广告账户中的网站转化事件标签（像素）；标签的 ID 是转化广告组的 `primary_web_event_tag` 所需的值 | | `x_ads_list_line_item_placements` | 按广告组产品类型列出有效的版位组合 | | `x_ads_get_account_stats` | 获取广告账户的同步分析数据（展示量、互动量、支出） | | `x_ads_get_active_entities` | 列出指定时间范围内指标发生变化的广告实体（请求账户统计数据前使用） | | `x_ads_get_campaign_reach` | 获取广告系列的覆盖人数和平均频次指标 | | `x_ads_search_targeting_interests` | 按名称搜索可定向的兴趣类别。 | | `x_ads_search_targeting_locations` | 按名称搜索可定向的位置。 | | `x_ads_list_cards` | 列出广告账户中的卡片 | | `x_ads_get_card` | 按 ID 获取单张卡片 | | `x_ads_list_media_library` | 列出广告账户中的媒体库对象 | | `x_ads_get_media_library_item` | 按媒体键获取单个媒体库对象 | | `x_ads_get_promoted_post` | 按 ID 获取单条推广帖子 | | `x_ads_get_targeting_criterion` | 按 ID 获取单条定向条件 | | `x_ads_list_post_previews` | 获取已发布或已安排帖子的渲染 HTML 预览 | | `x_ads_get_web_event_tag` | 按 ID 获取单个网站转化事件标签 | | `x_ads_get_media_upload_status` | 读取已连接 X 用户所拥有上传内容的处理状态。 |

21 个写入工具

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

工具	用途
x_ads_create_campaign	在广告账户中创建广告系列。
x_ads_update_campaign	重命名广告系列或暂停广告系列（entity_status=PAUSED）。
x_ads_activate_campaign	激活广告系列（将 entity_status 设为 ACTIVE）。
x_ads_create_line_item	在广告系列下创建广告组（广告组）。
x_ads_update_line_item	更新广告组的出价、预算、名称、排期、版位、目标、投放节奏、受众扩展（将 audience_expansion 设为 EXPANDED，以启用优化定位）或 entity_status。
x_ads_activate_line_item	激活广告组（将 entity_status 设为 ACTIVE）。
x_ads_promote_post	将帖子附加到广告组，作为其广告创意。
x_ads_add_targeting_criterion	为广告组添加一项定位条件（每项条件调用一次）。
x_ads_remove_targeting	从广告组中移除一项定位条件（撤销错误的定位设置）。
x_ads_create_ad_post	撰写仅用于推广（“nullcasted”）的帖子，将其用作广告创意。
x_ads_create_card	根据 JSON 组件负载创建卡片。
x_ads_delete_card	从广告账户中删除卡片。
x_ads_create_media_library_item	将现有媒体键注册为账户媒体库中的命名项目。
x_ads_delete_media_library_item	从广告账户中删除媒体库对象，默认采用预览模式。
x_ads_update_media_library_item	更新媒体库对象的元数据（例如名称、标题、描述），默认采用预览模式。
x_ads_create_web_event_tag	创建网站转化事件标签（像素）；返回的 ID 可设为广告组的 primary_web_event_tag，默认采用预览模式。
x_ads_delete_web_event_tag	删除网站转化事件标签，默认采用预览模式。
x_ads_update_web_event_tag	更新网站转化事件标签，默认采用预览模式。
x_ads_upload_media	将图片、GIF 或 MP4 视频片段上传到 X。
x_ads_rename_campaign	重命名 X Ads 广告系列。仅名称会更改。
x_ads_rename_line_item	重命名 X Ads 广告组。仅名称会更改。

1 个资源

URI	内容
x-ads://guide	此服务的账户范围、单位、写入工作流和媒体限制

许可证

Apache License 2.0。请参阅 NOTICE。

更多 getmcpads 项目

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

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