TikTok Ads

短片展示的是使用示例数据的托管版 getmcpads。从创意图库和提醒，到 Google Sheets 导出和批量启动，其 MCP Apps 均属于托管产品。此仓库提供独立的原生 API 工具。

35 个读取工具 · 30 个写入工具，默认禁用。

使用你自己的平台凭据，以及支持 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 发布的工具名称、参数和描述均未更改。server-card.json 已使用 Zod 4 的 JSON Schema 输出重新生成，其中部分约束的表达方式有所不同。

更早版本

版本	日期	主要更新
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/tiktok-ads。
1.0.0	2026 年 8 月 29 日	首个开源版本

完整更新日志 · 所有版本

源代码同步：SOURCE_SYNC.md。

升级说明

需要 Node.js 22.23.4、24.22.1、26.12.1 或更高版本。这些版本包含 2026 年 10 月的安全修复；如果服务器运行在更旧的版本上，会在 stderr 中打印警告。CI 覆盖 Node 22、24 和 26。

没有破坏性变更。 2.0 配置仍可继续使用。请注意：

• TIKTOK_ADVERTISER_IDS 是可选的。如果不设置，令牌可访问的所有广告主仍可访问，服务器会在 stderr 中打印一行建议。请将其设置为此服务器可使用的广告主。
• TIKTOK_ENABLE_WRITES 仍会将 1、yes 和 on 识别为 true，并在 stderr 中打印一行弃用提示。请使用 TIKTOK_ENABLE_WRITES=true。
• 2.0.1 版本忽略了 TIKTOK_ENVIRONMENT=sandbox，并将所有请求发送到生产环境。2.1.0 版本会将请求发送到 sandbox-ads.tiktok.com，并绑定到一个广告主：TIKTOK_ADVERTISER_IDS 中的唯一 ID，或 TIKTOK_ADVERTISER_ID。如果两者都未设置，则会拒绝 sandbox 调用。

已宣布将在 3.0.0 中变更： TIKTOK_ADVERTISER_IDS 将成为必填项，且只有精确值 true 才会启用写入。

重新使用已保存的参数前，请先查看当前工具架构。写入功能仍为可选，并且需要明确确认。托管创意集成和 MCP Apps UI 不在此版本范围内。

安装此版本

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

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

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

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

你将获得

35 个读取工具	广告系列、广告组、广告、创意、受众、像素、事件、Spark Ads、目录、投放诊断
30 个写入工具	默认关闭。用于创建和配置广告系列、广告组、广告及 Smart+ 实体，以及管理状态、预算、重命名和媒体上传。每项操作都会先预览，再应用
277 项指标	包括在客户端计算的衍生指标
16 个维度	带有兼容性矩阵，可在调用 API 前发现无效组合
5 项资源	模型可读取的实时目录：指标、维度、兼容性规则、12 个工作流方案
关键词研究	tiktok_search_keywords 和 tiktok_get_search_ads_maturity，用于 TikTok Search Ads
前向兼容读取	tiktok_get_read_endpoint、tiktok_get_entities_raw、tiktok_get_report_raw 可访问此服务器尚未建模的端点

查询规划器

TikTok 会拒绝许多指标和维度组合，而且其错误消息很少说明原因。 此服务器内置了兼容性矩阵，因此可以将无法执行的请求拆分为多个有效的 API 调用，并合并结果，而不是直接失败。

tiktok_validate_query 可让模型在消耗一次调用前检查组合。

此服务器替你处理的一种陷阱

即使调用失败，TikTok 也会返回 HTTP 200。 真正决定调用结果的是应用层的 code 字段。 如果客户端只信任 HTTP 状态码，就会向模型报告并不存在的成功，导致模型基于从未返回的数据进行推理。这里的每次调用都会先检查 code。

---

获取令牌

TikTok 需要两个值，而不是一个：访问令牌，以及该令牌所属的 App ID。

1. 在 TikTok for Business 开发者门户创建开发者应用。
2. 在应用页面记下 App ID 和 App Secret。
3. 为你想要访问的广告主账户授权。TikTok 按广告主授予访问权限， 因此，无论令牌允许什么，这里跳过的账户对服务都不可见。
4. 完成 OAuth 授权流程，将返回的 auth_code 兑换为 访问令牌。TikTok 的长期令牌不会按固定计划过期，但在 撤销授权时会被撤销。
5. 将令牌填入 TIKTOK_ACCESS_TOKEN，并将 App ID 填入 TIKTOK_APP_ID。

📖 TikTok API for Business 文档

首次调用时运行 tiktok_health_check。它会验证凭据，列出你实际可访问的广告主账户， 并报告缺少的内容，同时不会打印你的令牌。

需要哪些权限？

权限组	何时需要
报告和读取权限	**始终需要。**广告系列、广告组、广告、洞察
广告系列管理权限	仅当你设置 TIKTOK_ENABLE_WRITES=true 时需要
商品目录和 Business Center 权限	可选，用于 tiktok_get_shop_catalog_diagnostics

---

设置

Claude Desktop

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

{
  "mcpServers": {
    "tiktok-ads": {
      "command": "npx",
      "args": ["-y", "@getmcpads/tiktok-ads-mcp-server"],
      "env": {
        "TIKTOK_ACCESS_TOKEN": "your-token-here",
        "TIKTOK_APP_ID": "your-app-id-here",
        "TIKTOK_ADVERTISER_IDS": "your-advertiser-id"
      }
    }
  }
}

重启 Claude Desktop。向它询问："列出我的 TikTok 广告主账户"。

Claude Code

claude mcp add tiktok-ads --env TIKTOK_ACCESS_TOKEN=your-token --env TIKTOK_APP_ID=your-app-id --env TIKTOK_ADVERTISER_IDS=your-advertiser-id -- npx -y @getmcpads/tiktok-ads-mcp-server

Cursor

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

从源代码运行

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

配置

变量	默认值	说明
TIKTOK_ACCESS_TOKEN	none	**必填。**你的访问令牌
TIKTOK_APP_ID	none	**必填。**该令牌所属的 App ID
TIKTOK_ADVERTISER_IDS	none	**建议填写，自 3.0.0 起为必填。**此服务可访问的广告主 ID，以逗号分隔。设置后，任何其他广告主都会在发出请求前被拒绝，发现结果也只会列出这些广告主。未设置时，令牌可访问的所有广告主均可访问
TIKTOK_APP_SECRET	none	可选，用于需要应用身份验证的端点
TIKTOK_ADVERTISER_ID	none	可选的默认值，省去每次调用时传入该值。设置 TIKTOK_ADVERTISER_IDS 后，此值必须是其中之一
TIKTOK_BC_ID	none	可选的 Business Center ID。未设置时会读取 TIKTOK_BUSINESS_CENTER_ID
TIKTOK_ENABLE_WRITES	false	设为 true 会注册 30 个写入工具。直到 3.0.0，1、yes 和 on 仍可使用，但会显示弃用提示
TIKTOK_ENVIRONMENT	production	production 或 sandbox。Sandbox 会将每次调用绑定到一个广告主：TIKTOK_ADVERTISER_IDS 中唯一的 ID，或 TIKTOK_ADVERTISER_ID
LOG_LEVEL	info	debug、info、warn、error

你可以随时检查设置：

npm run doctor

---

写入工具为何会先提供预览

写入工具默认处于禁用状态。设置 TIKTOK_ENABLE_WRITES=true 即可启用。

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

// tiktok_update_adgroup_budget { advertiserId: "7...", adGroupId: "1...", budget: 50 }
{
  "applied": false,
  "action": "tiktok_update_adgroup_budget",
  "change": { "advertiser": "7...", "adGroup": "1...", "newBudget": 50,
              "budgetMode": "BUDGET_MODE_DAY" },
  "message": "Preview only, nothing was changed. Repeat the same call with confirm: true to apply this change to the live account."
}

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

这是有意为之。助手会编排这些调用，但可能选错广告主、选错广告系列，或把预算金额弄错几个数量级。强制预览能让错误在造成损失之前显现，也为人工干预提供了一个停止点，而协议本身并不能保证这一点。

还有一项保障措施：**tiktok_create_campaign 始终会创建状态为 DISABLE 的广告系列。**没有选项可以创建启用状态的广告系列。

工具	修改内容
tiktok_update_campaign_status / tiktok_update_adgroup_status	暂停或重新启用
tiktok_update_campaign_budget / tiktok_update_adgroup_budget	预算，使用账户货币
tiktok_create_campaign	创建广告系列，状态始终为 DISABLE

---

工具

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

35 个读取工具

| 工具 | 用途 | | --- | --- | | `tiktok_health_check` | 只读健康检查 TikTok 凭证、可访问的广告主及广告主信息。 | | `tiktok_list_advertisers` | 列出使用当前令牌可访问的所有 TikTok 广告主账户。 | | `tiktok_get_advertiser_info` | 获取特定 TikTok 广告主账户的详细信息：货币、时区、状态、余额。 | | `tiktok_get_campaigns` | 列出 TikTok 广告主账户的广告系列。 | | `tiktok_get_adgroups` | 读取完整的原生广告组配置，包括定向、自定义／类似受众引用及排除项、地理位置、语言、年龄／性别、版位、兴趣／行为、预算和排期。 | | `tiktok_get_targeting` | 读取已配置的广告组定向和受众引用：自定义／类似受众的纳入／排除项、地理位置、语言、年龄／性别、版位、兴趣和行为。 | | `tiktok_get_audience_report` | 按年龄或性别读取 TikTok 受众效果报告，支持广告主、广告系列、广告组或广告层级，并包括符合条件的 Smart+ 广告系列的投放数据。 | | `tiktok_get_ads` | 列出 TikTok 广告主的广告。 | | `tiktok_get_insights` | 使用当前原生／计算指标目录和查询规划，查询 TikTok Ads 效果洞察。 | | `tiktok_get_creatives` | 获取 TikTok 广告主账户中特定广告的创意详情（视频、图片、文本）。 | | `tiktok_get_audiences` | 列出 TikTok 广告主账户的自定义受众和类似受众。 | | `tiktok_search_keywords` | 获取 TikTok 搜索广告的关键词建议。 | | `tiktok_validate_query` | 在执行前验证 TikTok 指标／维度组合。 | | `tiktok_get_pixels` | 列出 TikTok 像素，并在权限允许时读取广告主的像素事件元数据。 | | `tiktok_get_events` | 发现广告主的像素／应用事件，或可访问的跟踪诊断信息。 | | `tiktok_get_delivery_status` | 汇总广告系列、广告组和广告的投放状态／operation_status，并提供简单诊断。 | | `tiktok_get_async_report_status` | 在异步报告端点可用时，根据 taskId 检查 TikTok 异步报告任务状态。 | | `tiktok_get_video_assets` | 在可用时，从 ad/get 和视频素材端点返回广告关联的 TikTok 视频素材元数据。 | | `tiktok_get_spark_ads` | 在可用时从广告字段返回 Spark Ads 上下文；如果不支持 Spark 专属字段，则采用保守的回退方式。 | | `tiktok_get_audience_details` | 在可访问 TikTok DMP 端点时，获取自定义／类似／已保存受众的详情。 | | `tiktok_get_shop_catalog_diagnostics` | 只读 TikTok Shop／商品目录／电商诊断信息。 | | `tiktok_get_search_ads_maturity` | 根据关键词／搜索词报告及可选的关键词推荐端点，诊断 TikTok 搜索广告成熟度。 | | `tiktok_get_creative_fatigue_recipes` | 根据广告层级的每日报告，查找可能的创意疲劳模式并返回只读刷新方案。 | | `tiktok_get_audience_overlap` | 只读诊断广告组、自定义受众、已保存受众和定向字段之间的受众重叠情况。 | | `tiktok_get_spark_organic_joins` | 在权限允许时，将可访问的 Spark Ads 字段与付费主页／帖子报告及可选的自然身份／帖子端点关联起来。 | | `tiktok_list_ad_videos` | 列出广告主的完整视频库（文件／视频／广告／搜索）：文件名、时长、尺寸、签名，以及可公开访问的预览和封面 URL。 | | `tiktok_list_ad_images` | 列出广告主的完整图片库（文件／图片／广告／搜索）：文件名、尺寸、签名、轮播可用性，以及签名有效期约为 30 天的公开图片 URL（image_url_expires_at 提供确切时刻）。 | | `tiktok_get_asset_urls` | 为特定 TikTok 素材库素材（file/video/ad/info 和 file/image/ad/info）重新解析新鲜且可公开获取的 URL。 | | `tiktok_get_entities_raw` | 使用调用方选择的原生字段、筛选、排序和分页，列出 TikTok 广告系列、广告组或广告。 | | `tiktok_get_report_raw` | 使用调用方选择的维度和指标，运行原生 TikTok BASIC 或 AUDIENCE 同步报告。 | | `tiktok_get_targeting_catalog` | 读取 TikTok 定向和规划目录：地理位置、语言、兴趣、行为、话题标签、搜索广告关键词建议／健康状况、设备、运营商、上下文标签、内容排除项和时区。 | | `tiktok_get_read_endpoint` | 高级的仅 GET TikTok Business API 备用入口，用于访问尚未由专用 MCP 工具建模的、文档中说明的 JSON 读取端点。 | | `tiktok_get_carousel_music` | 为标准非商品目录图片广告（单张卡片）或轮播广告中恰好上传的图片获取 TikTok 音乐推荐。 | | `tiktok_get_uploaded_video` | 从此广告主的媒体库读取一个已上传的视频。 | | `tiktok_get_write_context` | 在编辑或构建新配置前，读取确切的 TikTok 实体、父级设置以及广告主货币／时区。 |

30 个写入工具

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

工具	用途
tiktok_create_cta_portfolio	根据此广告主的 creative/cta/recommend 返回的确切获批建议，创建动态 CTA 组合。
tiktok_create_custom_identity	为 Pangle 或 Global App Bundle 创建由广告主拥有的 CUSTOMIZED_USER 广告身份。
tiktok_create_campaign_advanced	创建已禁用的经典 TikTok 广告系列。
tiktok_update_campaign_configuration	更新经典 TikTok 广告系列。
tiktok_create_adgroup	创建已禁用的经典 TikTok 广告组。
tiktok_update_adgroup_configuration	更新经典 TikTok 广告组。
tiktok_create_ads	创建已禁用的经典 TikTok 广告（视频、图片、轮播或获授权的 Spark 内容）。
tiktok_update_ads	更新经典 TikTok 广告（视频、图片、轮播或获授权的 Spark 内容）。
tiktok_create_smart_plus_campaign	创建已禁用的升级版 Smart+ TikTok 广告系列。
tiktok_update_smart_plus_campaign	更新升级版 Smart+ TikTok 广告系列。
tiktok_create_smart_plus_adgroup	创建已禁用的升级版 Smart+ TikTok 广告组。
tiktok_update_smart_plus_adgroup	更新升级版 Smart+ TikTok 广告组。
tiktok_create_smart_plus_ad	创建已禁用的升级版 Smart+ TikTok 广告（视频、图片、轮播或获授权的 Spark 内容）。
tiktok_update_smart_plus_ad	更新升级版 Smart+ TikTok 广告（视频、图片、轮播或获授权的 Spark 内容）。
tiktok_update_ad_status	暂停或重新启用一个经典广告。
tiktok_update_smart_plus_campaign_status	暂停或重新启用一个 Smart+ 广告系列。
tiktok_update_smart_plus_adgroup_status	暂停或重新启用一个 Smart+ 广告组。
tiktok_update_smart_plus_ad_status	暂停或重新启用一个 Smart+ 广告。
tiktok_update_smart_plus_material_status	暂停或重新启用一个升级版 Smart+ 广告中的指定创意素材。
tiktok_rename_campaign	重命名一个经典 TikTok 广告系列。
tiktok_rename_adgroup	重命名一个经典 TikTok 广告组。
tiktok_rename_ad	重命名一个经典 TikTok 广告。
tiktok_rename_advertiser	重命名 TikTok 广告账户（广告主）本身。
tiktok_upload_ad_image	从公开的 HTTPS 媒体 URL 或 base64 文件导入图片（最大 5 MiB）。
tiktok_upload_ad_video	从公开的 HTTPS 媒体 URL 或 base64 文件导入视频（最大 5 MiB）。
tiktok_update_campaign_status	暂停或重新启用 TikTok 广告系列。
tiktok_create_campaign	创建 TikTok 广告系列。
tiktok_update_campaign_budget	更改 TikTok 广告系列预算，币种为账户所用币种。
tiktok_update_adgroup_status	暂停或重新启用 TikTok 广告组。
tiktok_update_adgroup_budget	更改 TikTok 广告组预算。

5 个资源

URI	内容
tiktok://manifest	此服务公开的内容及其当前模式
tiktok://metrics	全部 277 项指标及其类别和格式
tiktok://dimensions	全部 16 个维度及其适用范围
tiktok://compatibility	兼容性矩阵
tiktok://recipes	12 个分步工作流

---

安全

该服务持有可读取实时广告账户、并可选择修改账户的凭据。 具体来说：

• 令牌绝不会写入日志。 调试输出会打印 Access-Token: [redacted]。
• 请求只会发送到 business-api.tiktok.com；当 TIKTOK_ENVIRONMENT=sandbox 时，则只会发送到 sandbox-ads.tiktok.com，且仅限 /open_api/v1.3/ 路径下。 任何其他主机或路径都会被拒绝，不会发起调用。已由测试覆盖。
• 设置 TIKTOK_ADVERTISER_IDS 后，只会访问这些广告主。 发送请求前会拒绝任何其他广告主，并将发现响应过滤为该列表。 已由测试覆盖。
• 每个请求都有 30 秒超时和 20 MB 响应大小限制。 在记录或返回服务提供方的错误文本前，会移除其中的令牌和应用密钥。
• 附加令牌后会拒绝重定向，因此重定向无法将你的凭据转发到其他位置。
• 通用读取路径会阻止修改类和 OAuth 端点。 已由测试覆盖。
• 不进行遥测。 除 TikTok Business API 外，该服务不会发起任何网络调用。 你可以通过在源代码中搜索 fetch 来验证这一点。

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

---

想要托管式、多平台版本？

如果你想使用此源而无需运行本地服务，试用托管版 TikTok Ads。 getmcpads 还可通过一个 MCP URL 连接广告、Search Console 和 GA4。 网站列出了可用的数据源和套餐限制；仍需连接账户。

1. 按照 TikTok Ads 连接指南操作。
2. 选择助手可以读取的账户或媒体资源。
3. 连接 Claude、 ChatGPT 或 Codex。
4. 尝试进行只读审核：“比较完整周期内的广告系列投放和转化趋势。指出缺失的数据，不要做任何更改。”

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

---

参与贡献

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

许可证

Apache License 2.0。另请参阅 NOTICE。

TikTok 和 TikTok for Business 是 ByteDance Ltd. 及其关联公司的商标。 本项目与 TikTok 或 ByteDance 无关，也未获得其认可或赞助。 这是一个独立的公共 API 客户端。

MCP 合约和桌面应用套件

每个工具都声明读取/写入注释、参数说明和结构化输出架构。成功调用会将载荷作为 structuredContent.result 提供；错误会保留 isError: true。生成的服务卡片仅包含定义。

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

更多 getmcpads 项目

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

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