ads-mcp-server

Google AdsおよびMeta Marketingのパフォーマンスデータ、キャンペーン設定、変更履歴をClaude (Cowork) に公開し、ライブのデイリーダッシュボードワークフローを実現するローカルMCPサーバーです。

機能

MCPに登録された3つのツール:

アーキテクチャ: プラットフォームごとに1時間あたり1回、広告×日単位の生データをプルしてparquetにキャッシュし、pandasですべての集計を導出します。ブレークダウンごとにAPIを呼び出すことはありません。

Related MCP server: Google Ads MCP Server

前提条件

• macOS / Linux

• Python 3.13 (pyenv推奨)

• uv パッケージマネージャー: brew install uv

• Google Ads APIアクセス — Google Ads APIの開始方法 を参照

• Meta Marketing APIアクセス — Marketing APIの開始方法 を参照

認証情報の設定リンク

インストール

cd ~/marketing-ds/ads-mcp-server
uv sync --extra dev

uv は .venv/ を作成し、 pyproject.toml で固定されたすべての依存関係をインストールします。

認証情報の設定

2つのオプションがあります:

オプションA — 既存の .env を指定 (すでに ~/marketing-ds/decision_science/.env にキーがある場合に推奨):

export ADS_MCP_ENV_FILE=/Users/jmacaggi/marketing-ds/decision_science/.env

オプションB — ローカルの .env を使用:

cp .env.example .env
# fill in the blanks

必要なキーは、それぞれ解説付きで .env.example にリストされています。

実行

ローカルでのテスト:

uv run ads-mcp-server

サーバーはstdio経由でMCPと通信します。Cowork (または任意のMCPクライアント) が必要に応じて起動します。

Claude (Cowork) への接続

~/.claude/claude_desktop_config.json に以下のブロックを追加します (存在しない場合は作成してください):

{
  "mcpServers": {
    "ads": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/jmacaggi/marketing-ds/ads-mcp-server",
        "run",
        "ads-mcp-server"
      ],
      "env": {
        "ADS_MCP_ENV_FILE": "/Users/jmacaggi/marketing-ds/decision_science/.env"
      }
    }
  }
}

Claude/Coworkを再起動します。 get_google_ads_report、 get_meta_ads_report、 get_campaign_settings ツールが表示されるはずです。

バックグラウンドデーモンは不要です。Coworkがセッションごとにプロセスを開始/停止します。

デイリープリウォーム (ライブダッシュボードに推奨)

キャッシュの有効性ルール: 昨日の日付 が含まれていればキャッシュは最新とみなされます。1日1回更新されます。その日の最初のユーザークエリが更新をトリガーしますが、大規模なアカウントで56日分をプルすると1〜3分かかる場合があります。

この待ち時間を避けるため、macOSのlaunchdを使用して午前6時にプリウォームをスケジュールします:

# Install
cp /Users/jmacaggi/marketing-ds/ads-mcp-server/launchd/com.jmacaggi.adsmcp.prewarm.plist \
   ~/Library/LaunchAgents/

launchctl load ~/Library/LaunchAgents/com.jmacaggi.adsmcp.prewarm.plist

# Verify it's scheduled
launchctl list | grep adsmcp

# Trigger immediately (test)
launchctl start com.jmacaggi.adsmcp.prewarm

# Logs
tail -f ~/marketing-ds/ads-mcp-server/logs/prewarm.stdout.log
tail -f ~/marketing-ds/ads-mcp-server/logs/$(date +%Y-%m-%d).log

毎朝午前6時に実行される内容:

1. Google Adsのパフォーマンス56日分、設定、変更イベント29日分をプル → キャッシュ

2. (Metaは現在無効 — 下記「Metaのステータス」を参照)

3. 更新スタンプ cache/google_lastrefresh.txt = 今日 を書き込み

Coworkを開く頃にはGoogleデータは最新状態になっており、ツール呼び出しは1秒未満で返ります。

アンインストール方法:

launchctl unload ~/Library/LaunchAgents/com.jmacaggi.adsmcp.prewarm.plist
rm ~/Library/LaunchAgents/com.jmacaggi.adsmcp.prewarm.plist

Metaのステータス (2026-05-07時点)

Metaツール (get_meta_ads_report, get_campaign_settings(platform="meta"|"both")) は 構造的には完成していますが、エンドツーエンドの検証はまだ完了していません。

動作するもの:

• パフォーマンスのプルは7日間のウィンドウに分割されます (Service temporarily unavailable / subcode 1504044 「結果が大きすぎる」エラーを回避)

• 広告レベルのデータは分割されます: 56日間の時系列には level=campaign、昨日のみのデータには level=ad を使用 (5分間のページネーションを回避)

• AdSetのプルは effective_status IN [ACTIVE, PAUSED] でフィルタリングされます (数千のアーカイブ済み広告セットのページネーションを回避)

ブロックされている点:

• 最初の大きなパフォーマンスの分割プル後、AdSetのプルがMetaの1時間あたりのレート制限 (code 17, subcode 2446079: "User request limit reached") に達しました。クールダウンは通常10〜60分です。

翌朝 (クォータがリセットされた後) に再テストするには:

# Remove --skip-meta from the launchd plist to enable Meta in pre-warm
sed -i '' '/<string>--skip-meta<\/string>/d' \
   ~/Library/LaunchAgents/com.jmacaggi.adsmcp.prewarm.plist
launchctl unload ~/Library/LaunchAgents/com.jmacaggi.adsmcp.prewarm.plist
launchctl load ~/Library/LaunchAgents/com.jmacaggi.adsmcp.prewarm.plist

# Or run manually
ADS_MCP_ENV_FILE=/Users/jmacaggi/marketing-ds/decision_science/.env \
   uv run python scripts/prewarm.py

Metaのレート制限が続く場合の代替案 (未実装):

• パフォーマンスプル用の非同期レポート実行 (async=True)

• より厳格な effective_status フィルタ ( ACTIVE のみ、一時停止を除外)

長時間実行されるバックグラウンドプロセスを好む場合 (オプション、Coworkには不要): nohup uv run ads-mcp-server > /tmp/ads-mcp.log 2>&1 & またはlaunchdのplistを使用してください。

オプション: CSVオーバーライド (APIをスキップ)

Google Ads UIはAPIクォータ制限なしでCSVレポートをエクスポートできます。CSVを cache/external/ にドロップすると、APIプルをオーバーライドできます:

cache/external/google_2026-05-07.csv
cache/external/meta_2026-05-07.csv

一致するCSVが存在し、かつparquetキャッシュよりも新しい場合、サーバーはAPIを呼び出さずにそれを読み込みます。レスポンスには metadata.data_source = "csv_override" が設定されるため、Coworkはそれを認識できます。

CSVの列スキーマはparquetと一致する必要があります (列名については src/ads_mcp_server/google_ads.py および meta_ads.py を参照: date, campaign_id, campaign_name, ad_id, ad_name, spend, impressions, clicks, conversions, ...)。

テスト

uv run pytest -v

すべてのテストはモックベースであり、ネットワーク呼び出しは行われません。以下をカバーします:

• classify_campaign (ブランド/ノンブランド/その他)

• diagnose (5状態分類器)

• 8週間の同じ曜日セレクターが正しい8つの日付を選択

• WoWデルタ + ゼロ除算

• Meta用の actions[] フィルタ

• スナップショットの差分 (古い値がnullの場合やプルーニングを含む)

• 認証情報がない場合にクリーンなエラーを返す (例外なし)

ログ

すべてのAPI呼び出しとエラーは logs/YYYY-MM-DD.log (1日1ファイル) に記録されます。

トラブルシューティング

• google-ads のインストール失敗: Python 3.13 (uv python pin 3.13) を確認し、システムで pip install grpcio が動作することを確認してください。Apple Siliconの場合: arch -arm64 uv sync。

• Metaトークンの期限切れ: ビジネス設定でシステムユーザートークンを再生成してください。長期有効トークンは60日間有効です。

• Coworkにツールが表示されない: ~/Library/Logs/Claude/mcp*.log で起動エラーを確認してください。GUIプロセスに対して uv が PATH にあることを確認してください (フルパスが必要な場合があります: which uv)。

• キャッシュが古い: cache/*.parquet を削除して強制的に再プルしてください。

ファイルマップ

src/ads_mcp_server/
  server.py        # MCP entry + tool handlers
  config.py        # env loading, validates creds
  google_ads.py    # 3 GAQL queries: perf, settings, change_event
  meta_ads.py      # Insights + AdSet pull
  snapshots.py     # Meta snapshot diff (Meta has no reliable change API)
  cache.py         # parquet + CSV override
  aggregate.py     # all pandas math
  classify.py      # Brand/NB/Other
  diagnose.py      # 5-state diagnosis
  date_ranges.py   # window resolution + 8wk DoW
  retry.py         # exponential backoff
  logging_setup.py # daily file logs
  schema.py        # response shape constants