TikTok GMV Max

TikTok GMV Max MCP

TikTok Business（Marketing）API 用の読み取り専用 Model Context Protocol サーバーです。GMV Max を標準でサポートしています。GMV Max キャンペーン、通常の広告、Business Center の予算状況をアシスタントに尋ねると、ショップのタイムゾーンと米ドルで回答します。

複数ショップの TikTok Shop レポートスタックの背後で、本番環境にて毎日稼働しています。そのため、単純な API ラッパー以外のコードの大半は、生の API で正しく処理されない内容に対応しています。レポートの日付は、広告アカウントのタイムゾーンからショップのタイムゾーンに合わせて調整されます。米ドル以外のアカウントは、その日の為替レートで換算されます。TikTok で発生する一時的な 51010 タイムアウトは再試行されます。

ysntony/tiktok-ads-mcp（MIT）のフォークとして始まりました。元のプロジェクトは、6 つの主要なキャンペーン／レポートツールをカバーしています。このプロジェクトでは、GMV Max、タイムゾーン調整済みレポートと期間レポート、クリエイティブ、Business Center の財務情報、トレンドのハッシュタグを追加し、tiktok-gmvmax-mcp として別途公開しています。Python のインポートパッケージは引き続き tiktok_ads_mcp のため、同じ環境に両方のディストリビューションをインストールしないでください。

ツール（24 個、すべて読み取り専用）

GMV Max

ツール	返される内容
get_gmvmax_campaigns_tool	ステータスと ROI 保護情報を含む GMV Max キャンペーン
get_gmvmax_campaign_info_tool	1 つのキャンペーンの予算、入札額、商品、スケジュール
get_gmvmax_reports_tool	GMV Max のパフォーマンスレポート（/gmv_max/report/get/）
get_gmvmax_report_aligned_tool	ショップのタイムゾーンに合わせた 1 日分のデータ。時間別データから再構成した費用、総収益、注文数、ROI
get_gmvmax_range_report_tool	指定した期間の費用／GMV／注文数／ROI の集計
get_gmvmax_videos_tool	ストアで GMV Max に利用できる動画
get_gmvmax_store_list_tool	GMV Max 広告主に紐付けられたストア

アカウント、キャンペーン、広告

ツール	返される内容
get_business_centers_tool	トークンから参照できる Business Center
get_authorized_ad_accounts_tool	認可済みの広告主アカウントすべて
get_campaigns_tool / get_ad_groups_tool / get_ads_tool	フィルタリング可能なキャンペーン、広告グループ、広告の一覧
get_identities_tool	広告主に認可された TikTok ID（クリエイターアカウント）
get_video_info_tool	動画 ID に基づく動画アセットの URL、ポスター、再生時間

レポート

ツール	返される内容
get_reports_tool	カスタムディメンションと指標を含む統合レポート
get_ads_report_aligned_tool	手動入札広告のショップのタイムゾーンに合わせた 1 日分のデータ。費用、GMV、注文数、ROAS
get_ads_range_report_tool	指定した期間の手動入札広告の集計
get_creative_report_tool	クリエイティブ単位の動画インサイト（エンゲージメント、再生指標）

Business Center の財務情報

ツール	返される内容
get_advertiser_balance_tool	広告主ごとの残高と基本情報（1 回の呼び出しにつき ID は最大 100 件）
get_bc_balance_tool	Business Center の利用可能な資金
get_bc_account_cost_tool	指定した期間における、BC 配下の広告アカウントごとの費用
get_bc_transactions_tool	BC または広告主レベルでの入金と差し引き
get_bc_budget_changelog_tool	広告主の予算を変更したユーザーと変更日時

検索

ツール	返される内容
get_trending_list_tool	国別のトレンドハッシュタグ（7 日または 30 日）。日次履歴も指定可能

インストール

Python 3.10 以降が必要です。

uvx tiktok-gmvmax-mcp          # run without installing
# or
pip install tiktok-gmvmax-mcp  # provides the `tiktok-gmvmax-mcp` command

設定

TikTok for Business 開発者ポータルでアプリを作成し、必要なエンドポイント（広告アカウント、キャンペーンと広告、レポート、GMV Max、Business Center）への読み取り権限を付与して、有効期間の長いアクセストークンを生成します。

変数	必須	説明
TIKTOK_APP_ID	はい	アプリ ID
TIKTOK_SECRET	はい	アプリシークレット
TIKTOK_ACCESS_TOKEN	はい	アクセストークン
TIKTOK_ACCESS_TOKEN_2	いいえ	2つ目のトークン（例：別の Business Center 用）。権限エラーが発生した場合に試します
TIKTOK_ADVERTISER_ID	いいえ	デフォルトの広告主
TIKTOK_SANDBOX	いいえ	サンドボックス API を使用する場合は true
TIKTOK_REQUEST_TIMEOUT	いいえ	秒数。デフォルトは 30
TIKTOK_ADS_PROXY	いいえ	Business API の呼び出しにのみ使用するプロキシ URL
LARK_BOT_CACHE_DIR	いいえ	FX レートのキャッシュ保存先（デフォルトは ~/.cache/lark-bot）

0.2 より前のバージョンでは、トークンは TIKTOK_ACCESS_TOKEN_XINCHENG / TIKTOK_ACCESS_TOKEN_ZECHENG から読み取られます。これらの名前も引き続き使用できます。

Claude Desktop / Claude Code（mcpServers）：

{
  "mcpServers": {
    "tiktok-gmvmax": {
      "command": "uvx",
      "args": ["tiktok-gmvmax-mcp"],
      "env": {
        "TIKTOK_APP_ID": "your_app_id",
        "TIKTOK_SECRET": "your_secret",
        "TIKTOK_ACCESS_TOKEN": "your_access_token"
      }
    }
  }
}

知っておくとよい動作

• タイムゾーン。 TikTok は、広告アカウントのタイムゾーンに基づいて日別のデータを報告します。*_aligned_tools は時間別の行を取得し、ショップのタイムゾーンの日単位に再集計するため、広告費をショップの注文と正確に照合できます。
• 通貨。 USD 以外のアカウントの費用と収益は、その日の ECB の仲値（Frankfurter）で USD に換算されます。レート API が停止している場合は、その呼び出しに限り、組み込みの概算レート表を使用します。このレートはキャッシュされません。それ以外の通貨は換算されず（レート 1.0）、エラーがログに記録されます。
• 再試行。 コード 51010（TikTok バックエンドのタイムアウト）は、クライアント層でバックオフを伴って再試行されます。レート制限エラーと 5xx エラーも再試行されます。
• mcp 1.x と 2.x。 どちらも動作します。サーバーは MCPServer（2.x）をインポートし、使用できない場合は FastMCP（1.x）にフォールバックします。

開発

git clone https://github.com/Buer2333/tiktok-ads-mcp && cd tiktok-ads-mcp
python -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest tests -q

問題の報告や PR は歓迎します。動作を変更する場合は、テストも追加してください。

変更履歴

0.2.0

• tiktok-gmvmax-mcp として公開しました（PyPI の名前 tiktok-ads-mcp は上流プロジェクトに属しています）。
• 汎用の TIKTOK_ACCESS_TOKEN / TIKTOK_ACCESS_TOKEN_2 に対応しました。従来の名前も引き続き使用できます。
• CLI のログは stderr に出力されるため、stdio プロトコル用の stdout はクリーンな状態に保たれます。
• FX：API の停止中に使用されたフォールバックレートが、恒久的にキャッシュされなくなりました。
• フォーク以降、18 個のツールを追加しました：GMV Max、タイムゾーン整合済みおよび期間指定のレポート、クリエイティブ、Business Center の財務、ID、トレンド。また、アカウントの検出、51010 の再試行、USD への換算、mcp 2.x との互換性も追加しました。

0.1.x（上流）

• 6 個のコアツール、非同期 httpx クライアント、FastMCP サーバー。ysntony/tiktok-ads-mcp を参照してください。

ライセンス

MIT。LICENSE を参照してください。