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 認證支持