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 開発者アプリ
• Claude Desktop など、ローカルの stdio サーバーに対応した MCP クライアント

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 の設定

MCP クライアントが cwd を正しく適用しない場合でもサーバーがプロジェクトディレクトリから起動するように、uv --directory を使います。

"/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"
      }
    }
  }
}

Windows で Claude が 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 を、env の下にある MCP クライアントの設定に追加します。

認証フロー

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 にコミットしたり、課題の報告で共有したりしないでください。
• ご自身のマシンに保存し、通常の OS アカウント権限で保護してください。
• ローカルサーバーと 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 - 広告主アカウントに紐付けられたピクセルの一覧を取得します。
• tiktok_ads_get_pixel_event_stats - 指定した期間のピクセルイベントのアクティビティを取得します。

実装の監査

現在、MCP ツールとして一覧表示されるのは、実際の OAuth、ローカルのトークン状態、または TikTok Marketing API の呼び出しに接続されているものだけです。このリポジトリでは、プレースホルダーやモックのツールは公開していません。

ツール	裏付けとなる実装
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	campaign_ids による絞り込みを指定して、TikTok Marketing API の campaign/get/ を呼び出します。
tiktok_ads_get_adgroups	TikTok Marketing API の adgroup/get/ を呼び出します。
tiktok_ads_get_adgroup_details	adgroup_ids による絞り込みを指定して、TikTok Marketing API の adgroup/get/ を呼び出します。
tiktok_ads_get_ads	TikTok Marketing API の ad/get/ を呼び出します。
tiktok_ads_get_ad_details	ad_ids による絞り込みを指定して、TikTok Marketing API の ad/get/ を呼び出します。
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	report_type=AUDIENCE を指定して、TikTok Marketing API の report/integrated/get/ を呼び出します。
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 を起動しましたが、プロジェクトディレクトリからコマンドを実行しませんでした。

cwd に頼らず、uv の引数にプロジェクトディレクトリを指定するように MCP 設定を修正してください。

"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、トークンファイル、App Secrets、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 を参照してください。

サポート

問題や質問がある場合は、このリポジトリにイシューを作成してください。