Mcp Google Ads

mcp-google-ads

サーバーを再起動せずに、複数のクライアントまたは社内の広告アカウントを単一の MCP サーフェスで扱いたい運用担当者向けの、複数アカウント対応 Google Ads MCP サーバーです。

リリース状況：ベータパッケージです。バージョンは pyproject.toml の 0.1.0 です。

利用目的を選ぶ

対象	まず読むもの	次に読むもの
MCP クライアントにサーバーを接続する方	docs/start-here.md	以下のクイックスタート
アカウントの切り替えと再試行を監査する方	docs/architecture.md	gads/server.py
パッケージのメタデータを確認する方	pyproject.toml	accounts.example.json

アーキテクチャ

flowchart TD
  U[AI operator] --> C[MCP client]
  C --> S[FastMCP server]
  S --> M[Account manager]
  M --> F[Accounts config]
  S --> Q[GAQL query helpers]
  Q --> R[Retry wrapper]
  R --> A[Google Ads API]
  A --> R --> S

リクエストの流れ

flowchart TD
  P[Operator asks for account or campaign data] --> T[Selected MCP tool]
  T --> A[Resolve named or default account]
  A --> B[Build Google Ads client]
  B --> C[Run GAQL query]
  C --> D{API call succeeds?}
  D -- yes --> E[Normalize rows and return]
  D -- retryable --> F[Backoff and retry]
  F --> D
  D -- no --> G[Return error payload]

クイックスタート

1. パッケージをインストールします。

python -m pip install mcp-google-ads-multi

2. アカウント設定テンプレートをコピーし、アカウントを追加します。

mkdir -p ~/.config/mcp-google-ads
cp accounts.example.json ~/.config/mcp-google-ads/accounts.json

3. MCP クライアントに登録します。

{
  "mcpServers": {
    "google-ads": {
      "command": "uvx",
      "args": ["mcp-google-ads-multi"],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your-developer-token",
        "GOOGLE_ADS_ACCOUNTS_CONFIG": "/Users/you/.config/mcp-google-ads/accounts.json"
      }
    }
  }
}

利用可能なツール

ツールグループ	ツール	目的
アカウント選択	list_accounts, set_default_account, list_customers	アカウントのルーティングを管理し、アクセス可能な顧客を確認します
費用の概要	get_account_summary, compare_periods	期間ごとのアカウントレポート
キャンペーン分析	list_campaigns, get_campaign_performance	キャンペーン一覧と期間指定の指標
クエリレベルの詳細	get_keyword_performance, search_terms_report, get_ad_performance	キーワード、検索語句、広告のレポート

実行時の根拠

主張	根拠
パッケージのエントリーポイントは安定しています	pyproject.toml の mcp-google-ads-multi = "gads.server:main"
複数アカウントのルーティングを第一級機能として扱います	gads/server.py の AccountManager() と set_default_account()
クエリは再利用可能なヘルパーを経由します	gads/query.py と gads/retry.py
設定はファイルで管理します	accounts.example.json にアカウント設定の形式が記載されています

リポジトリの構成

パス	目的
gads/server.py	FastMCP のツールサーフェス
gads/accounts.py	アカウント設定、OAuth／サービスアカウントの読み込み
gads/query.py	GAQL の実行ヘルパー
gads/retry.py	API 呼び出しの再試行動作
docs/start-here.md	セットアップ、検証、一般的な問題
docs/architecture.md	コンポーネントの概要とリクエストのライフサイクル

検証

チェック項目	コマンド
インポートをコンパイル	python -m compileall gads
パッケージをビルド	python -m build
README／ドキュメントのリンクがローカルであること	rg '\\]\\(([^)]+\\.md)\\)' README.md docs/

ライセンス

MIT

新しいタスク向けのプロジェクト情報

タスク固有の仕様は INDEX.md を参照してください。製品の方向性が関係する場合は prompt.md も確認してください。過去の例から現在のタスクを決めないでください。