TikTok Ads MCP 故障排查指南

TikTok Ads MCP 无法工作时，身份验证只是可能原因之一。应按客户端配置、服务进程、工具发现、身份和权限、API 响应、网络行为、数据请求的顺序，从外到内排查。

1. 先定位失败层级

记录客户端、MCP 提供方、账户、完整请求、时间和完整错误文本，并判断属于哪种情况：服务无法启动；工具无法发现；工具可见但调用被拒绝；某个账户为空或无权限；请求返回 API 错误、超时或限流；请求成功但数据为空或异常。

这样可以避免把配置错误误判为凭据问题。

2. 检查服务和客户端

确认命令、运行时、包、参数、工作目录和环境变量符合提供方当前文档。修改 MCP 配置后重新加载或重启客户端。查看启动输出中是否有包缺失、JSON 无效、不支持字段或进程立即退出。

不要把密钥放进提问，也不要提交到代码仓库。分享日志前必须脱敏 Token。

3. 检查工具和权限

服务在线但没有 TikTok Ads 工具时，检查服务声明的能力以及客户端是否真的重新加载。工具存在但返回权限错误时，确认广告主账户、Business Center 关系、用户或应用身份，以及最小权限范围。

身份验证成功不代表该身份可以读取目标广告主账户。

4. 检查请求和 API 响应

先使用一个账户、较短日期范围、少量指标和尽可能少的拆分维度。记录账户、时区、货币、转化事件、筛选条件、分页和请求维度。大查询可能超时或触发限制，即使小查询正常。

遇到 API 错误时保留状态码、请求结构、服务提供的关联 ID 和重试行为。权限或参数校验错误不应盲目重复重试。

5. 解释空数据或异常数据

空结果可能表示没有投放、日期范围过窄、转化延迟、账户错误、时区边界、筛选不匹配或维度不可用。要求 AI 区分“数值为零”和“没有返回”，并明确账户和日期范围重复查询。

如果总数和 TikTok Ads 界面不一致，先比较时区、归因、货币、状态筛选、报表延迟和聚合层级，再判断 MCP 数据是否异常。

6. 创建最小复现

将问题缩小为一个客户端、一个服务、一个账户、一个短日期范围、一个只读工具和一个脱敏错误。记录不含密钥的配置形状、客户端和服务版本、时间，以及换账户或客户端后是否仍然发生。

7. 安全恢复

修正设置后，先测试账户列表，再测试广告报表，最后才考虑任何具备写入能力的动作。首次成功请求保持只读。不要为了消除错误而直接轮换凭据、扩大权限或修改线上广告。

配置说明请看 入门指南，客户端教程请看 Codex、Claude Code 和 Cursor。