Google Ads MCP

Google Ads MCP は、Google Ads アカウントを調査するための、ローカルでセキュリティ最優先の読み取り専用 MCP サーバーおよび Codex プラグインです。バージョン 0.1.0 は、制限付きのインベントリ、レポート、メタデータ、変更履歴、および安全な GAQL ツールを公開します。書き込み、アップロード、スケジュール設定、削除、オプティマイザー、またはホスト型トランスポートの機能は含まれません。

公開 Python ディストリビューションの名前は google-ads-operator-mcp です。製品名とコマンドは引き続き Google Ads MCP および google-ads-mcp です。

セキュリティ境界

• すべてのアカウントスコープのリクエストは、プロファイルと顧客 ID の両方を指定します。

• Google の認証情報は、Application Default Credentials またはリポジトリ外の明示的な所有者専用 google-ads.yaml に保持されます。

• accounts.json には、開発者トークンの環境変数名のみを含めることができ、トークン自体は決して含めることはできません。

• allowWrites は false でなければならず、それ以外の値は拒否されます。

• 本番アダプターによって構築されるのは、GoogleAdsService、CustomerService、GoogleAdsFieldService のみです。

• ツールは正規化された行のみを受け取り、Google クライアントや生のレスポンスエンベロープを受け取ることはありません。

• MCP モードでは、stdout は JSON-RPC 用に予約されています。診断情報とサニタイズされた失敗コードは stderr に出力されます。

本番アカウントに接続する前に、SECURITY.md、PRIVACY.md、および脅威モデルをお読みください。

Related MCP server: merchant-center-mcp

要件

• Python 3.11、3.12、または 3.13

• uv

• 開発者トークンを使用した Google Ads API アクセス

• ADC、または別途保存された所有者専用の google-ads.yaml

開発者トークン、Python クライアント設定、および Application Default Credentials については、Google の公式ガイダンスを参照してください。

ローカルセットアップ

uv sync --frozen --all-groups
uv run --frozen google-ads-mcp version
uv run --frozen google-ads-mcp config init

公開リリース後は、スタンドアロン CLI を uv tool install google-ads-operator-mcp==0.1.0 でインストールすることもできます。最終的なクリーンプラグイン受理ゲートには、ソースツリーのコピーではなく、リリース版のプラグインアーカイブを使用してください。

~/.config/google-ads-mcp/accounts.json を編集し、公開アカウント ID を置き換えてから、所有者専用の権限を復元します：

ローカルのシークレットマネージャーから GOOGLE_ADS_DEVELOPER_TOKEN を公開し、その値をリポジトリやシェル履歴に入れないようにしてから、次のコマンドを実行します：

chmod 600 ~/.config/google-ads-mcp/accounts.json
gcloud auth application-default login
uv run --frozen google-ads-mcp config validate
uv run --frozen google-ads-mcp auth doctor --profile production-read-only

開発者トークン、OAuth リフレッシュトークン、クライアントシークレット、ADC JSON、または YAML の内容を、このリポジトリ、Issue、ターミナルのトランスクリプト、またはチャットに貼り付けないでください。

設定

設定の優先順位は、--config、次に GOOGLE_ADS_MCP_CONFIG、その次に ~/.config/google-ads-mcp/accounts.json です。

{
  "profiles": [
    {
      "name": "production-read-only",
      "loginCustomerId": "1234567890",
      "defaultCustomerId": "0987654321",
      "auth": {
        "type": "adc",
        "developerTokenEnv": "GOOGLE_ADS_DEVELOPER_TOKEN"
      },
      "allowWrites": false
    }
  ]
}

既存の Google クライアント YAML には、{"type":"googleAdsYaml","path":"/absolute/owner-only/google-ads.yaml"} を使用します。相対パスとシンボリックリンクは拒否されます。サーバーは、YAML 認証情報を作業ディレクトリやリポジトリから検索することはありません。

CLI

google-ads-mcp version
google-ads-mcp config init
google-ads-mcp config validate
google-ads-mcp auth doctor --profile <name>
google-ads-mcp accounts discover --profile <name>
google-ads-mcp serve --stdio

MCP ツール

v0.1 で固定されたサーフェスは次のとおりです：

auth_check                customers_list
customer_get              customer_hierarchy
account_health            campaigns_query
campaign_inventory        resource_metadata
reports_catalog           report_run
change_events_query       gaql_validate
gaql_search

型付きリストはページごとに最大 200 項目を返します。1 回の Google 読み取りは、正規化された 1,000 行に制限されます。5 分間のカーソルはプロファイルと正確なリクエストにバインドされ、プロファイルごとのアクティブなカーソルは最大 20 個です。安全な GAQL にはカーソルがなく、コメントのない単一の SELECT、非機密リソース、および LIMIT 1..1000 が必要です。

パラメータ、エビデンスのセマンティクス、およびレポートの動作については、docs/tools.md を参照してください。

Codex プラグイン

リポジトリのルートがプラグインのルートです。.mcp.json は ./bin/google-ads-mcp-launcher を呼び出します。これは stdio 経由で固定された uv 環境のみを実行します。暗黙の google-ads-operator スキルは、すべてのアカウント文字列を信頼できないデータとして扱い、利用できない変更ツールを提案することはありません。

このリポジトリは、個人用マーケットプレイスエントリを意図的に作成または変更しません。リリースアーカイブのインストールは、受理時に別途検証されます。

検証

uv run --frozen ruff check .
uv run --frozen pyright
uv run --frozen pytest
uv run --frozen python scripts/validate_read_only.py
uv run --frozen python scripts/validate_gaql_templates.py
uv run --frozen python ~/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py .
uv run --frozen python ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/google-ads-operator

自動検証はライブアカウントの受理ではありません。docs/acceptance.md に記載されているテストアカウントと本番読み取り専用のゲートは、v0.1.0 の前に引き続き必須です。

ライセンス

Apache-2.0。Google Ads は Google LLC の商標です。このプロジェクトは独立しており、Google による推奨を受けるものではありません。