TikTok Shop

tiktok-shop-mcp

TikTok Shop Partner API 用の TikTok Shop Partner API 向け Model Context Protocol（MCP）サーバーです。Claude やその他の MCP クライアントから、複数のショップの注文、財務、商品、分析、アフィリエイトの実績を照会できます。

TikTok Shopを運営するセラーや代理店向けに構築されており、「昨日、米国のショップでは何が売れた？」「今週、どのSKUが人気？」「6月の精算明細を取得して」といった質問に、ブラウザーでスクレイピングすることなく、公式APIを直接利用してAIアシスタントが回答できます。

機能

• 複数ショップ対応 — 1つのJSONファイルで任意の数のショップを設定できます。各ツールのオプション引数 seller_name（部分一致）でショップを選択できます
• 22種類のツール — 注文、財務、商品カタログ、ショップ／動画／SKUの分析、アフィリエイトのベストセラー、返品／キャンセルに対応します
• 人にわかりやすい日付 — Unixタイムスタンプの代わりに start_date=2026-07-01 とIANAタイムゾーンを指定できます。変換はサーバーが処理します
• トークンのライフサイクル管理 — 会話を離れることなく、有効期限の確認とアクセストークンの更新を行えます（単一ショップまたは全ショップ）
• デフォルトで高い耐障害性 — すべてのリクエストは mcp-retry を通じて実行されます（429／5xx／ネットワークエラーに対する指数バックオフ＋ジッター）
• ショップに対する読み取り専用アクセス — ツールが商品リストを編集したり、商品を作成したり、ファイルをアップロードしたりすることはありません。サーバーが書き込むのは、自身の shops.json のみです。トークンの更新時には、所有者のみがアクセスできる（0600）権限が設定されます。多層防御として、Partner Centerアプリには読み取りスコープのみを許可してください

ツール

グループ	ツール
ショップと認証	list_shops · refresh_token · refresh_all_tokens
注文	get_shop_orders · get_order_detail · search_returns · search_cancellations
財務	get_shop_statements · get_shop_transactions
商品	get_shop_products · get_product_detail
ショップ分析	get_shop_performance · get_shop_performance_hourly · get_shop_products_performance · get_product_performance · get_shop_videos_performance · get_sku_performance · get_customer_service_performance
動画とアフィリエイト	get_account_video_gmv · get_videos_bestselling · get_creators_bestselling · get_products_bestselling

インストール

pip install tiktok-shop-mcp

または、ソースから、テストで使用するバージョンに直接依存関係を固定して、仮想環境にインストールできます。

git clone https://github.com/Buer2333/tiktok-shop-mcp.git
cd tiktok-shop-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/pip install --no-deps -e .

requirements.txt では、すべてのAPI呼び出しをラップし、トークンにアクセスする mcp-retry を含む、直接のランタイム依存関係のバージョンを正確に固定しています。推移的依存関係（pydantic、starletteなど）のバージョンは固定していません。完全に再現可能なインストールを行うには、pip-compile --generate-hashes を使ってロックファイルを生成してください。ピンを更新する場合は、そのリリースでの変更内容を確認してから行ってください。

互換性

mcp 1.xと2.xの両方で動作します。mcp 2.0では FastMCP が MCPServer（mcp.server.mcpserver）に改名され、mcp.server.fastmcp は例外を発生させるスタブになりました。server.py はtry-v2-except-v1シムを介してインポートします。テストは1.28.1と2.1.1で成功しており、requirements.txt では2.1.1に固定しています。

設定

認証情報は、リポジトリの外部にある JSON ファイル（デフォルトは ~/.config/tiktok-mcp/shops.json。TIKTOK_SHOP_CONFIG 環境変数で変更できます）に保存されます。サーバーがプロジェクトフォルダー内の shops.json を読み込むことはないため、そこにコピーを置いても、誤って取り込まれたり同期・コミットされたりすることはありません。このファイルのアクセス権は所有者のみにしてください。

chmod 700 ~/.config/tiktok-mcp && chmod 600 ~/.config/tiktok-mcp/shops.json

セットアップスクリプトは、トークンのバックアップ（shops.json.bak.* と recovery/ フォルダー）をファイルの隣に作成します。ショップが正常に動作するようになったら削除してください。また、小さな shops.json.lock ファイルも同じ場所にあります。これはサーバー、cron リフレッシャー、セットアップスクリプトが同時にファイルへ書き込むのを防ぐためのものなので、そのままにしておいてください。

[
  {
    "seller_name": "MY SHOP US",
    "seller_base_region": "US",
    "app_key": "...",
    "app_secret": "...",
    "access_token": "TTP_...",
    "refresh_token": "TTP_...",
    "shop_id": "...",
    "shop_cipher": "..."
  }
]

TikTok Shop Partner Centerでアプリを作成すると、app_key と app_secret を取得できます。その後、ショップを認可してトークンを取得してください。shop_id と shop_cipher は、認可済みショップのエンドポイントから返されます。同梱の probe_authorized_shops.py スクリプトを使って取得することもできます。

3 つの *_bestselling ツールを使うには、Bestellers スコープを持つアプリのショップが必要です。リストはプラットフォーム全体を対象とするため、そのようなショップは 1 つあれば十分です。TIKTOK_SHOP_BESTSELLERS_SHOP にそのショップの seller_name を設定すると（部分一致でも可）、seller_name が省略された場合にツールがそのショップを使用します。設定されていない場合は、shops.json 内の最初のショップが使用されます。

Claude Code

claude mcp add tiktok-shop -- tiktok-shop-mcp

Claude Desktop ／その他の MCP クライアント

{
  "mcpServers": {
    "tiktok-shop": {
      "command": "tiktok-shop-mcp",
      "env": { "TIKTOK_SHOP_CONFIG": "/path/to/shops.json" }
    }
  }
}

プロンプトの例

• 「ショップの一覧と、各ショップのトークンの有効期限を表示して」
• 「2026-07-18 の Eastern 時間で、MY SHOP US の注文を表示して」
• 「過去 7 日間で、最も多くの GMV をもたらしたクリエイターは誰？」
• 「昨日の時間別 GMV の推移を、その前日と比較して」
• 「すべてのショップのトークンを更新して」

アーキテクチャ

tiktok_shop_mcp/
├── server.py     # FastMCP app — tool definitions, date handling, error envelope
├── client.py     # Signed HTTP client (HMAC-SHA256 request signing, via mcp-retry)
├── config.py     # Multi-shop credential loading & resolution
└── tools/        # One module per API domain (orders, finance, products, analytics…)

すべてのツールは、構造化された JSON を返します。エラーは {"error": true, "message": …, "suggestion": …} の形式で返されるため、モデルは自力で修正できます（例：期限切れのトークンを更新して再試行する）。

免責事項

これは独立したオープンソースプロジェクトであり、TikTok との提携や、TikTok による推奨を受けたものではありません。TikTok Shop API の利用には、TikTok 独自の利用規約が適用されます。

ライセンス

MIT