Tiktok Ads Mcp Server

TikTok Ads MCP 服务

用于集成 TikTok Ads API 的本地 Model Context Protocol（MCP）服务。它支持 Claude Desktop 等 MCP 客户端连接 TikTok Ads，使用 TikTok Business 应用进行身份验证，并使用只读工具查询广告系列、检查广告组和广告、生成效果报告、细分受众、查看广告主信息、像素和定向位置。

托管选项

本仓库面向希望运行本地 TikTok Ads MCP 服务的用户。

如果你不想安装 Python、管理依赖项或配置 TikTok 开发者应用，AdsMCP 提供托管的远程 MCP 服务：

AdsMCP 远程 MCP 服务设置指南

本 README 的其余部分介绍本地设置。

此服务的功能

• 身份验证：从 MCP 客户端启动并完成 TikTok Ads OAuth。
• 广告系列查询：列出广告系列、查看广告系列详情、列出广告组并检查广告。
• 效果分析：按常见日期范围获取广告系列、广告组、广告和受众指标。
• 受众和帐户数据：检索自定义受众、广告主信息、位置 ID、像素和像素事件统计数据。
• 只读操作：公开的 MCP 工具注册表不提供创建广告系列、创建广告组、上传创意素材或其他写入操作。

先决条件

你需要：

• Python 3.10 或更高版本
• 用于依赖管理的 uv
• 拥有 Marketing API 访问权限的 TikTok For Business 帐户
• 具有 App ID 和 App Secret 的 TikTok 开发者应用
• 支持本地 stdio 服务的 MCP 客户端，例如 Claude Desktop

安装 uv

macOS 和 Linux：

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows PowerShell：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

安装后，确认 uv 可用：

uv --version

配置桌面 MCP 客户端前，找到 uv 的绝对路径：

macOS 和 Linux：

whereis uv
which uv

如果客户端无法按名称找到 uv，请使用 whereis uv 或 which uv 返回的路径作为 MCP command 值。

Windows PowerShell：

where.exe uv

常见路径如下：

• macOS/Linux：/Users/<your-name>/.local/bin/uv
• Windows：C:\\Users\\<your-name>\\.local\\bin\\uv.exe

本地安装

克隆仓库并安装依赖项：

git clone https://github.com/AdsMCP/tiktok-ads-mcp-server.git
cd tiktok-ads-mcp-server
uv sync

找到项目目录的绝对路径。你将在 MCP 配置中将此路径用作 uv --directory 的值：

macOS 和 Linux：

pwd

Windows PowerShell：

Get-Location

验证项目环境是否可以导入 MCP：

uv run python -c "from mcp.server import Server; print('ok')"

你应该会看到：

ok

重要提示：使用 uv 运行服务

除非你已在该确切的 Python 环境中手动安装所有依赖项，否则不要将 MCP 客户端配置为使用系统 python 或 python3 运行此服务。

请使用：

uv run python run_server.py

不要使用：

python run_server.py
python3 run_server.py

原因：MCP 桌面应用启动的 Python 通常与你在终端中使用的不同。如果该 Python 环境没有安装 mcp 包，服务将因以下错误而退出：

No module named 'mcp'

uv run 会让 MCP 客户端使用此项目的依赖环境。

配置 Claude Desktop

Claude Desktop 从以下位置读取其 MCP 服务配置：

macOS：

~/Library/Application Support/Claude/claude_desktop_config.json

Windows：

%APPDATA%\\Claude\\claude_desktop_config.json

Linux 路径因发行版和客户端软件包而异，但通常位于：

~/.config/Claude/

macOS / Linux 配置

使用 uv --directory，确保服务从项目目录启动，即使 MCP 客户端未能正确应用 cwd。

要填写 "/absolute/path/to/tiktok-ads-mcp-server"，请在克隆的仓库中打开终端并运行：

pwd

将输出的值用作 --directory 参数。如果 Claude 找不到 uv，请将 "uv" 替换为 whereis uv 或 which uv 返回的绝对路径，例如 "/Users/yourname/.local/bin/uv"。

{
  "mcpServers": {
    "tiktok-ads": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/tiktok-ads-mcp-server",
        "run",
        "python",
        "run_server.py"
      ],
      "env": {
        "TIKTOK_APP_ID": "your_app_id",
        "TIKTOK_APP_SECRET": "your_app_secret"
      }
    }
  }
}

Windows 配置

JSON 路径中使用转义反斜杠。要查找项目路径，请在克隆的代码仓库中打开 PowerShell 并运行：

Get-Location

将打印出的值用作 --directory 参数，并在 JSON 中将每个 \ 转义为 \\：

{
  "mcpServers": {
    "tiktok-ads": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\path\\to\\tiktok-ads-mcp-server",
        "run",
        "python",
        "run_server.py"
      ],
      "env": {
        "TIKTOK_APP_ID": "your_app_id",
        "TIKTOK_APP_SECRET": "your_app_secret"
      }
    }
  }
}

如果 Claude 在 Windows 上找不到 uv，请使用完整路径：

"command": "C:\\Users\\yourname\\.local\\bin\\uv.exe"

编辑配置后，请完全重启 Claude Desktop。

TikTok 应用设置

1. 前往 TikTok For Business Developer Portal。
2. 创建或打开一个开发者应用。
3. 复制 App ID 和 App Secret。
4. 确保 TikTok 应用中配置的重定向 URI 与此服务使用的重定向 URI 相符。默认情况下，此项目使用：

https://adsmcp.com

5. 将 App ID 和 App Secret 添加到 MCP 客户端配置的 env 下。

身份验证流程

连接 MCP 服务后：

1. 在 MCP 客户端中运行 tiktok_ads_login。
2. 打开该工具返回的授权 URL。
3. 在 TikTok 中批准访问权限。
4. 从重定向 URL 中复制 code 参数。
5. 使用该代码运行 tiktok_ads_complete_auth。
6. 运行 tiktok_ads_auth_status，确认账户已通过身份验证。

令牌存储与安全

完成 OAuth 后，TikTok 访问令牌和刷新令牌会存储在本地的以下位置：

~/.tiktok_ads_mcp/tokens.json

此文件用于让本地 MCP 服务在你完成身份验证后调用 TikTok Marketing API。请像对待密码一样保护它：

• 不要将其提交到 Git，也不要在问题报告中分享。
• 将其保存在自己的设备上，并通过常规操作系统账户权限加以保护。
• 如果想断开本地服务与 TikTok 账户的连接，请删除此文件。

本地服务仅会存储你授权的 TikTok 账户的令牌，且仅用于代表该账户发起经过身份验证的 TikTok API 调用。

可用工具

本地服务当前通过其 MCP 注册表公开以下工具。 此列表是开源软件包的权威来源。

身份验证

• tiktok_ads_login - 开始 TikTok Ads OAuth 身份验证。
• tiktok_ads_complete_auth - 使用授权码完成 OAuth。
• tiktok_ads_auth_status - 检查当前身份验证状态。
• tiktok_ads_switch_ad_account - 切换到其他广告主账户。

广告系列管理

• tiktok_ads_get_campaigns - 获取广告主账户的广告系列。
• tiktok_ads_get_campaign_details - 获取指定广告系列的详细信息。
• tiktok_ads_get_adgroups - 获取某个广告系列的广告组。
• tiktok_ads_get_adgroup_details - 获取指定广告组的详细信息。
• tiktok_ads_get_ads - 按广告系列、广告组、广告 ID 或状态获取广告。
• tiktok_ads_get_ad_details - 获取指定广告的详细信息。

效果与分析

• tiktok_ads_get_campaign_performance - 获取广告系列级指标。
• tiktok_ads_get_adgroup_performance - 获取广告组级指标。
• tiktok_ads_get_ad_performance - 获取广告级指标。
• tiktok_ads_get_audience_breakdown - 按受众维度细分广告系列、广告组或广告的效果。
• tiktok_ads_wasted_spend_audit - 对没有转化信号的支出和点击运行只读审计。

创意素材与受众

• tiktok_ads_get_custom_audiences - 列出自定义受众。
• tiktok_ads_get_advertiser_info - 获取账户级广告主详细信息，例如货币、时区、状态、行业、国家/地区和创建时间。
• tiktok_ads_get_location_info - 解析 TikTok 定向位置 ID。
• tiktok_ads_get_pixel_list - 列出关联到广告主账户的 Pixel。
• tiktok_ads_get_pixel_event_stats - 获取指定日期范围内的 Pixel 事件活动。

实现审计

只有连接到真实 OAuth、本地令牌状态或 TikTok Marketing API 调用的 MCP 工具才会列出。本仓库不提供占位或模拟工具。

工具	后端实现
tiktok_ads_login	启动 TikTok OAuth 并返回授权 URL。
tiktok_ads_complete_auth	用 OAuth 代码换取 TikTok 令牌并在本地保存。
tiktok_ads_auth_status	检查本地配置和已保存的令牌状态。
tiktok_ads_switch_ad_account	完成身份验证后切换本地活动广告主账户。
tiktok_ads_get_campaigns	调用 TikTok Marketing API campaign/get/。
tiktok_ads_get_campaign_details	调用 TikTok Marketing API campaign/get/，并使用 campaign_ids 筛选。
tiktok_ads_get_adgroups	调用 TikTok Marketing API adgroup/get/。
tiktok_ads_get_adgroup_details	调用 TikTok Marketing API adgroup/get/，并使用 adgroup_ids 筛选。
tiktok_ads_get_ads	调用 TikTok Marketing API ad/get/。
tiktok_ads_get_ad_details	调用 TikTok Marketing API ad/get/，并使用 ad_ids 筛选。
tiktok_ads_get_campaign_performance	在广告系列层级调用 TikTok Marketing API report/integrated/get/。
tiktok_ads_get_adgroup_performance	在广告组层级调用 TikTok Marketing API report/integrated/get/。
tiktok_ads_get_ad_performance	在广告层级调用 TikTok Marketing API report/integrated/get/。
tiktok_ads_get_audience_breakdown	调用 TikTok Marketing API report/integrated/get/，并设置 report_type=AUDIENCE。
tiktok_ads_wasted_spend_audit	只读工作流，调用 campaign/get/、adgroup/get/ 和 report/integrated/get/。
tiktok_ads_get_custom_audiences	调用 TikTok Marketing API dmp/custom_audience/list/。
tiktok_ads_get_advertiser_info	调用 TikTok Marketing API advertiser/info/，并通过 report/integrated/get/ 补充近期消耗日期。
tiktok_ads_get_location_info	调用 TikTok Marketing API tool/targeting/info/。
tiktok_ads_get_pixel_list	调用 TikTok Marketing API pixel/list/。
tiktok_ads_get_pixel_event_stats	调用 TikTok Marketing API pixel/event/stats/。

路线图

计划涵盖的领域：

• 扩大 GMV Max 广告系列的支持范围。
• 为广告系列、广告组、广告和素材提供安全的写入操作。
• 创意和素材管理。
• 完整的异步报告生命周期：创建、状态查询和下载。
• 定向探索和受众管理。

故障排除

Failed to spawn process: No such file or directory

MCP 客户端无法找到你配置的命令。

解决方法：

• 如果 uv 位于应用的 PATH 中，请使用 "command": "uv"。
• 否则请使用完整路径，例如：

"command": "/Users/yourname/.local/bin/uv"

No module named 'mcp'

你使用系统 Python 而不是项目环境运行服务。

请修改 MCP 配置，使用：

"command": "uv",
"args": ["--directory", "/path/to/tiktok-ads-mcp-server", "run", "python", "run_server.py"]

然后运行：

cd /path/to/tiktok-ads-mcp-server
uv sync

can't open file '//run_server.py'

MCP 客户端启动了 uv，但没有在项目目录中运行命令。

请修改 MCP 配置，将项目目录放入 uv 参数中，而不要依赖 cwd：

"command": "uv",
"args": ["--directory", "/path/to/tiktok-ads-mcp-server", "run", "python", "run_server.py"]

缺少 TikTok API 凭据

服务未收到 TIKTOK_APP_ID 或 TIKTOK_APP_SECRET。

解决方法：

• 在 MCP 客户端配置的 env 下添加这两个值。
• 修改配置后重启 MCP 客户端。

OAuth 成功，但工具仍提示未通过身份验证

检查令牌文件是否存在：

ls ~/.tiktok_ads_mcp/tokens.json

如果要重新开始身份验证，请删除令牌文件，然后再次运行 tiktok_ads_login：

rm ~/.tiktok_ads_mcp/tokens.json

修改配置后，Claude Desktop 仍显示旧错误

完全退出并重新打开 Claude Desktop。在 macOS 上，仅关闭窗口有时并不足够。

安全说明

• 不要提交 .env、令牌文件、应用密钥或 OAuth 代码。
• 妥善保管 ~/.tiktok_ads_mcp/tokens.json，不要公开。
• 使用仅具备所需权限的 TikTok 开发者应用。
• 当前公开的 MCP 注册表只能读取 TikTok Ads 对象。写入操作仍在规划中，在开放前应仔细审核。

开发

安装依赖：

uv sync

运行测试：

uv run --extra dev pytest

手动运行服务：

uv run python run_server.py

许可证

本项目采用 MIT License 许可。详情请参阅 LICENSE。

支持

如有问题或疑问，请在此代码库中创建议题。