Tiktok Ads MCP Server

🚀 TikTok Ads MCP Server

TikTok Ads MCP Server 是一个用于 TikTok 广告 API 集成的模型上下文协议（MCP）服务器。此服务器能让像 Claude 这样的 AI 助手与 TikTok 广告活动进行交互，提供全面的活动管理、分析和优化功能。

它是 AdsMCP 项目的一部分，该项目为广告平台提供 MCP 服务器。

✨ 主要特性

• 活动管理：创建、读取和更新广告活动及广告组。
• 效果分析：获取详细的效果指标和洞察。
• 受众管理：处理自定义受众和定向选项。
• 创意管理：上传和管理广告创意。
• 报告生成：生成并下载自定义效果报告。

📦 安装指南

前提条件

• Python 3.10 及以上版本
• 拥有 API 访问权限的 TikTok For Business 账户
• TikTok Ads 开发者账户并完成应用注册

本地安装

# 克隆仓库
git clone <repository-url>
cd adsmcp-server

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # 在 Windows 系统上使用：venv\Scripts\activate

# 安装依赖
pip install -e .

使用 uv（推荐）

# 使用 uv 进行安装
uv sync

📚 详细文档

MCP 客户端配置

将以下内容添加到你的 MCP 客户端配置中（例如，Claude Desktop）：

{
  "mcpServers": {
    "tiktok-ads": {
      "command": "python",
      "args": ["/path/to/adsmcp-server/run_server.py"],
      "cwd": "/path/to/adsmcp-server",
      "env": {
        "TIKTOK_APP_ID": "your_app_id",
        "TIKTOK_APP_SECRET": "your_app_secret",
      }
    }
  }
}

可用工具

认证相关

• 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_campaign_performance - 获取广告活动的效果指标，支持详细指标
• tiktok_ads_get_adgroup_performance - 获取广告组的效果指标，并提供细分数据

认证流程

TikTok Ads API 设置

1. 注册为开发者
   • 访问 TikTok For Business 开发者门户
   • 创建开发者账户
   • 注册你的应用
2. 获取 API 凭证
   • 从已注册的应用中获取应用 ID 和应用密钥
   • 通过 OAuth 流程生成访问令牌
   • 记录你的广告主 ID
3. OAuth 流程（用于生产环境）
   • 实现 OAuth 2.0 流程以进行用户授权
   • 自动处理令牌刷新
   • 安全存储令牌

安全最佳实践

• 切勿将 API 凭证提交到版本控制系统。
• 使用环境变量存储敏感数据。
• 实施适当的令牌轮换机制。
• 监控 API 使用情况和速率限制。
• 所有通信都使用 HTTPS。

API 速率限制

TikTok Ads API 有以下限制：

• 每个应用每小时 1000 个请求
• 10 个并发请求
• 特定端点可能有额外限制

服务器内置了速率限制和重试逻辑。

错误处理

服务器提供全面的错误处理：

• API 速率限制管理
• 令牌过期处理
• 网络连接问题处理
• 无效参数验证

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

🔧 技术支持

如有问题或疑问，请在此仓库中创建一个 issue。

更新日志

v0.1.0（初始版本）

• 基本的 TikTok Ads API 集成
• 广告活动和广告组管理
• 效果报告
• OAuth 认证支持