Skip to main content
Glama
deenesjakoruzh
jmacaggi-gfm

ads-mcp-server

by jmacaggi-gfm
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

ads-mcp-server

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

機能

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

ツール

目的

get_google_ads_report(date_range, breakdown)

パフォーマンス + 診断 + 56日間の時系列 + WoW + 8週間のDoW比較 + キャンペーン設定 + 変更履歴

get_meta_ads_report(date_range, breakdown)

Googleと同じ形式。コンバージョンは META_CONVERSION_EVENT_NAME でフィルタリング

get_campaign_settings(platform)

google / meta / both の設定 + 変更履歴

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

Related MCP server: mcp-marketing-analytics

前提条件

認証情報の設定リンク

認証情報

取得場所

GOOGLE_ADS_DEVELOPER_TOKEN

Google Ads UI → ツール → APIセンター

GOOGLE_ADS_CLIENT_ID / CLIENT_SECRET

https://console.cloud.google.com → OAuth 2.0クライアント (デスクトップアプリ)

GOOGLE_ADS_REFRESH_TOKEN

google-ads をインストール後、 python -m google.ads.googleads.examples.authentication.generate_user_credentials を実行

GOOGLE_ADS_CUSTOMER_IDS

カンマ区切り、ダッシュなし。Google Ads UIの右上から確認

GOOGLE_ADS_LOGIN_CUSTOMER_ID

MCCマネージャーアカウントID、ダッシュなし

META_APP_ID / META_APP_SECRET

https://developers.facebook.com → マイアプリ → 設定 → ベーシック

META_ACCESS_TOKEN

https://business.facebook.com → ビジネス設定 → システムユーザー → 新しいトークンを生成 (長期有効、 ads_read 権限付き)

META_AD_ACCOUNT_ID

Meta広告マネージャ → 左上のアカウントピッカー。形式: act_XXXXXXXXX

インストール

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

Available Tools

3 tools
get_campaign_settingsC

Current campaign settings + 56-day change history per platform.

ParametersJSON Schema
NameRequiredDescriptionDefault
platformYes

TDQS

C2.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully convey behavioral traits. It discloses that the tool returns both settings and a 56-day history, but does not indicate whether it is read-only, any authentication needs, rate limits, or what triggers destructive actions. The behavior is partially described but lacks completeness.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, making it very concise, but it omits important details such as parameter semantics and usage context. Conciseness is achieved at the expense of completeness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no output schema, no annotations), the description is insufficient. It does not explain the output structure, whether the data is aggregated per platform, or provide examples. The lack of detail makes it hard for an AI agent to fully understand the tool's capabilities.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has one parameter 'platform' with enum values, but the description does not explain the parameter's meaning beyond 'per platform'. It fails to clarify what 'both' implies or how the parameter affects the output. With 0% schema description coverage, the description adds no value over the schema itself.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves 'current campaign settings + 56-day change history per platform', which is a specific verb+resource. However, it does not explicitly differentiate itself from sibling tools like get_google_ads_report or get_meta_ads_report, which are focused on ads reports rather than settings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives such as get_google_ads_report or get_meta_ads_report. It does not mention exclusion criteria or context for usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_google_ads_reportA

Pull Google Ads performance. Returns account totals, campaign-type breakdown, top-50 per-ad rows with diagnosis, 56-day daily series, and WoW + 8-week DoW comparisons. Set include_campaign_settings=True to also return per-campaign settings (target CPA, daily budget, diagnosis, utilization) for ENABLED campaigns only.

ParametersJSON Schema
NameRequiredDescriptionDefault
date_rangeYes
breakdownYes
include_campaign_settingsNoIf true, attach campaign_settings list to the response. Defaults to false to keep payload small.

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, but the description details return components and the conditional behavior of include_campaign_settings (only for ENABLED campaigns).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences, no fluff, front-loaded with purpose and outputs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Description covers essential behavioral and parameter details despite lack of output schema; minor gaps in rate limits or authentication info.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is low (33%), but the description adds meaning to parameters by linking them to return elements (e.g., 'campaign-type breakdown' for breakdown enum).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Pull Google Ads performance' and lists specific outputs, distinguishing it from siblings like get_meta_ads_report and get_campaign_settings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies its use for Google Ads performance but does not explicitly guide when to use this tool over siblings or provide exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_meta_ads_reportB

Pull Meta Ads performance. Same shape as get_google_ads_report. Conversions filtered to META_CONVERSION_EVENT_NAME.

ParametersJSON Schema
NameRequiredDescriptionDefault
date_rangeYes
breakdownYes

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It only mentions the output shape similarity and a conversion filter, but lacks details on side effects, rate limits, authentication needs, or other behavioral traits. This is minimal disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with two short sentences, each providing distinct value. It front-loads the key information and avoids fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description should explain the report contents. It mentions a conversion filter but does not list other metrics or describe the full structure. Relying on the shape of get_google_ads_report is insufficient without that tool's description being present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description should add meaning to parameters. It does not explain the 'date_range' or 'breakdown' parameters beyond their enum values, which are self-explanatory but not enriched. This is a significant gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The name and description clearly indicate this tool retrieves Meta Ads performance data. The verb 'Pull' is specific, and the description explicitly states it is analogous to get_google_ads_report, which distinguishes it from sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by comparing to get_google_ads_report, but does not provide explicit guidance on when to use this tool versus alternatives or any prerequisites. No exclusions or when-not-to-use information is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedget_campaign_settings
    • First observedget_google_ads_report
    • First observedget_meta_ads_report
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.2/5.0

Scored across 3 tools

Disambiguation5/5

Each tool targets a distinct area: campaign settings, Google Ads performance, and Meta Ads performance. No overlap; descriptions clearly differentiate them.

Naming Consistency5/5

All tool names follow a consistent 'get_' prefix with the specific resource (campaign_settings, google_ads_report, meta_ads_report). Consistent snake_case pattern.

Tool Count4/5

Three tools is minimal but appropriate for a focused ads reporting and settings retrieval server. Could be expanded but current count is reasonable for the stated purpose.

Completeness2/5

Only read operations are exposed; no create, update, or delete tools for campaigns or ads. Significant gaps for a full ads management workflow.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Google Ads MCP Server

    jgdeutsch
    A
    license
    Not graded
    quality
    D
    maintenance
    Provides access to Google Ads API for comprehensive campaign analytics, enabling conversational ad performance analysis with Claude Code.
    25 npm
    2
    MIT
  • OQVA Marketing MCP by oqva-digital

    OQVA Marketing MCPofficial

    oqva-digital
    A
    license
    A
    quality
    B
    maintenance
    Connect Claude to your marketing data from Google and Meta, enabling read and write operations on Search Console, Analytics, Tag Manager, Business Profile, and Meta platforms.
    35
    Apache 2.0