← 返回指南

指南 / troubleshooting

TikTok Ads MCP 故障排查：连接、认证、权限与数据问题

按最短路径排查 TikTok Ads MCP 的服务器配置、OAuth、账户权限、工具加载、超时、空报表和 Ads Manager 数据差异。

作者：AdsDecide更新于 2026-08-20

这篇指南用于排查 TikTok Ads MCP 最常见的连接和数据问题。建议从最上层开始逐项检查：不要在服务器尚未连接时调提示词，也不要在账户权限错误时反复重新安装客户端。

完整排查通常需要 5–20 分钟。本文所有验证都只读取配置、连接状态和广告数据。

开始前先保存这些信息

信息示例是否可以公开
客户端及版本Codex 桌面版、Claude Code 版本号、Cursor 版本号可以
操作系统macOS、Windows、Linux可以
服务器模式渐进加载或完整加载可以
服务器地址官方地址可以
错误时间2026-08-20 10:30，含时区可以
错误文本完整错误码和提示去除敏感内容后可以
广告主 ID完整 ID不公开，只保留末 4 位
密码、Cookie、令牌、回调地址任何认证凭据绝不保存或分享

截图前遮盖客户名称、完整广告主 ID、业务数据和任何令牌。

先用症状定位层级

症状最可能的层级首先检查
MCP 列表中没有服务器客户端配置地址、配置范围、是否保存和重新加载
有服务器但工具为 0工具加载传输类型、地址结尾、客户端重启
一直要求登录OAuth浏览器用户、弹窗、回调和认证状态
已连接但账户为空账户权限OAuth 用户与 Ads Manager 用户是否一致
只有部分账户Business Center 分配用户是否被分配到每个广告账户
账户存在但报表为空查询范围广告主 ID、日期、时区、状态和筛选条件
报表与界面不同指标口径时区、今天、归因、事件、币种和层级
查询很慢或超时请求规模工具模式、日期、维度和分批方式

第 1 步：核对官方服务器地址

TikTok 当前提供：

模式地址特征
渐进加载https://business-api.tiktok.com/open_mcp/tt-ads-mcp-layer初始约 40 个核心工具，其他工具按需发现
完整加载https://business-api.tiktok.com/open_mcp/tt-ads-mcp-flat连接时加载约 400 个工具

常见填写错误：

  • 把 TikTok Ads Manager 网页地址当成 MCP 地址。
  • 复制时漏掉 https:// 或最后的 layer/flat。
  • 地址前后带空格、引号或中文标点。
  • 选择本地 STDIO，而不是远程 Streamable HTTP/HTTP。
  • 同名服务器存在两个不同地址，客户端加载了错误配置。

检查点： 配置中只有预期的 TikTok Ads 服务器，传输方式和地址完全正确。

第 2 步：服务器没有出现在客户端

按顺序检查：

  1. 确认添加服务器后已经保存。
  2. 检查配置保存范围：全局、用户或项目。
  3. 重新加载窗口或重启客户端。
  4. 打开客户端的 MCP 状态页，而不是只看聊天工具列表。
  5. 检查配置文件语法；JSON 不能有多余逗号，TOML 的节名称不能重复。
  6. 企业环境中确认管理员没有禁止个人 MCP 服务器。

客户端入口：

  • Codex：设置 → MCP 服务器，或输入 /mcp。
  • Claude Code：执行 claude mcp list，在会话中输入 /mcp。
  • Cursor：自定义 → MCP，并检查服务器是否启用。

检查点： 服务器至少出现在状态列表中。此时需要认证不算失败。

第 3 步：服务器可见但工具为 0

  1. 确认远程传输方式为 Streamable HTTP 或 HTTP。
  2. 核对官方地址的 layer/flat 结尾。
  3. 重新加载客户端，让它重新初始化服务器。
  4. 等待完整加载模式完成工具发现。
  5. 查看客户端错误详情，记录 HTTP 状态码或初始化错误。
  6. 如果团队设置了工具允许列表，确认至少允许读取类工具。

渐进加载模式初始工具较少不等于工具丢失；真正异常是服务器明确显示 0 个工具或初始化失败。

检查点： 至少能看到读取账户或报表所需的工具。

第 4 步：OAuth 不断循环或回调失败

按以下顺序处理：

  1. 在默认浏览器退出错误的 TikTok 用户。
  2. 登录确实拥有目标广告账户权限的 TikTok for Business 用户。
  3. 允许当前站点打开弹窗和本地回调。
  4. 暂时停用会拦截登录或跨站跳转的浏览器扩展。
  5. 回到客户端，从 TikTok Ads 服务器重新发起认证。
  6. 授权后等待浏览器完成跳转，再返回客户端。
  7. 客户端仍显示旧状态时，刷新 MCP 页面或重启一次。

只有在上述步骤无效时，才使用客户端提供的清除认证或断开连接功能，然后重新授权。只处理 TikTok Ads 这一项，不要批量删除其他 MCP 配置。

不要把回调地址、授权码或令牌发送到聊天中。某些客户端会要求把完整回调地址粘贴回专用认证输入框；只在该输入框中操作。

检查点： 状态从“需要认证”变为“已连接”，并且浏览器不再循环登录。

第 5 步：已认证但账户列表为空

先在 Ads Manager 中验证同一个用户：

  1. 打开 Ads Manager。
  2. 确认右上角或账户选择器中的用户身份。
  3. 切换到目标广告账户。
  4. 确认可以打开报表。
  5. 再回到客户端执行最小账户列表查询。

最小提示词：

请仅使用 TikTok Ads MCP 的读取工具，列出当前授权用户可以访问的广告主账户。
只返回账户名称、广告主 ID、状态、时区和币种。
字段不可用时明确标记，不要猜测，也不要修改任何内容。

如果 Ads Manager 可见而 MCP 为空，记录登录用户、客户端时间、服务器模式和错误文本，再重新授权一次。

第 6 步：只能看到部分广告账户

这是典型的 Business Center 资产分配问题：

  • 用户属于 Business Center，不代表自动拥有其中所有广告账户。
  • 合作伙伴关系存在，不代表每个成员都被分配到对应资产。
  • OAuth 只能带入当前用户已有的账户权限。
  • 某些账户可能已移除、冻结或使用不同的登录身份管理。

请让 Business Center 管理员逐个检查目标广告账户的人员分配和查看权限。权限调整后，先在 Ads Manager 确认可见，再刷新或重新认证 MCP。

检查点： MCP 列表与 Ads Manager 中同一用户的账户范围一致。

第 7 步：工具返回权限错误

记录以下内容：

  • 哪个读取请求失败。
  • 广告主 ID 的末 4 位。
  • HTTP 状态码或平台错误码。
  • 同一账户是否能在 Ads Manager 查看相同层级。
  • 其他账户是否能成功执行相同查询。

如果只有一个账户失败，优先检查该账户分配或状态；如果所有账户都失败，优先检查 OAuth 会话、团队策略或服务器连接。

不要通过扩大到管理员权限来跳过诊断。先确认读取报表所需的最小权限。

第 8 步：查询超时、加载慢或触发频率限制

先缩小请求，而不是重复提交：

  1. 只查一个广告主账户。
  2. 日期缩短为最近 3 个完整自然日。
  3. 先查广告系列层级，不查广告组和广告。
  4. 指标保留消耗、展示、点击和转化。
  5. 成功后再逐批增加层级和指标。

完整加载模式在首次连接时需要处理更多工具；渐进加载模式可能在请求时发现额外工具。两者的短暂等待都不等于失败。

遇到频率限制时，停止重复请求，等待客户端或服务器提示的重试时间。不要并行发送多个相同大报表。

第 9 步：账户存在但报表为空

使用最小数据查询：

请仅使用 TikTok Ads MCP 的读取工具查询广告主 ID 1234567890123456789。
日期为该账户时区内截至昨天的最近 3 个完整自然日。
只按广告系列返回状态、消耗、展示、点击和转化，并写明实际起止日期、时区、币种和筛选条件。
请区分“数值为 0”“没有返回记录”和“指标不可用”，不要修改任何内容。

然后检查：

  • 广告主 ID 是否属于当前授权用户。
  • 该日期内账户是否真实产生消耗。
  • 是否错误筛选了状态、目标或层级。
  • 日期是否被账户时区移动到无数据区间。
  • 账户是否暂停、冻结或尚未开始投放。
  • 选择的转化事件是否适用于该广告目标。

检查点： 即使没有转化，也应能说明是否有消耗和展示，以及为什么结果为空。

第 10 步：数据与 Ads Manager 不一致

用同样条件逐项对齐：

  1. 广告主 ID。
  2. 账户时区。
  3. 起止日期，并确认是否包含今天。
  4. 币种。
  5. 报表层级：账户、广告系列、广告组或广告。
  6. 状态和其他筛选条件。
  7. 点击定义。
  8. 主要转化事件。
  9. 归因窗口和报表归因口径。
  10. 数据延迟和去重逻辑。

最常见差异是 Ads Manager 默认包含今天，而提示词使用截至昨天的完整自然日。转化和转化价值也可能晚于消耗和点击回传。

要求 AI 在表格前打印所有查询参数，然后在 Ads Manager 手工设置相同条件复核 1–2 个高消耗广告系列。

第 11 步：判断是否需要切换加载模式

不要把切换地址当成通用修复。只在以下情况下尝试：

  • 完整加载模式因工具数量在客户端中明显变慢。
  • 渐进加载模式无法发现完成特定任务所需的工具。
  • TikTok 或客户端官方文档明确建议该客户端使用另一模式。

切换时一次只保留一个 TikTok Ads 配置，重新认证后先运行账户列表，再运行最小报表。不要同时配置 flat 和 layer 并使用相同名称。

第 12 步：生成最小复现记录

仍未解决时，整理：

客户端与版本：
操作系统：
服务器模式：渐进加载 / 完整加载
服务器地址：
发生时间和时区：
服务器状态：
工具数量：
OAuth 状态：
广告主 ID：仅末 4 位
最小只读提示词：
完整错误文本：已移除敏感信息
Ads Manager 中同一用户是否可见：是 / 否
最近一次成功时间：

发送给支持人员前再次检查，确保没有密码、Cookie、令牌、授权码、完整回调地址、完整广告主 ID 或客户业务数据。

恢复后的验收顺序

修复后不要直接运行大报表，按顺序验证：

  1. 服务器出现在 MCP 列表中。
  2. 认证状态为已连接。
  3. 工具列表不为空。
  4. 最小账户列表能返回正确账户。
  5. 最近 3 个完整自然日的广告系列报表有数据。
  6. Ads Manager 中抽查的消耗与日期条件一致。
  7. 最后再恢复 7 天或 14 天的完整分析。

只要其中一步失败，就停在该层排查。

凭据与执行安全

  • 不要把密码、Cookie、令牌、授权码或完整回调地址写入日志、截图和提示词。
  • 故障排查只使用读取工具；任何写入审批都应拒绝。
  • 只清除 TikTok Ads 的认证或配置，不要批量重置其他连接。
  • 团队账户权限应按最小范围分配，不要为了排错临时授予不必要的管理权限。

官方参考资料与客户端教程