google-ads-mcp

Google Ads MCP Server

このスキルは、Claude Code、Claude Desktop、Cursor、または任意の MCP クライアントから Google Ads API にライブアクセスするための google-ads-mcp サーバーを設定します。

クイックセットアップ

1. インストール

pip install git+https://github.com/itallstartedwithaidea/google-ads-mcp.git

2. 認証情報を設定

.env ファイルを作成するか、環境変数を設定します。

GOOGLE_ADS_DEVELOPER_TOKEN=your-developer-token
GOOGLE_ADS_CLIENT_ID=your-oauth-client-id
GOOGLE_ADS_CLIENT_SECRET=your-oauth-client-secret
GOOGLE_ADS_REFRESH_TOKEN=your-refresh-token
GOOGLE_ADS_LOGIN_CUSTOMER_ID=123-456-7890

または、既存の google-ads.yaml を指定します。

GOOGLE_ADS_CREDENTIALS=/path/to/google-ads.yaml
GOOGLE_ADS_LOGIN_CUSTOMER_ID=123-456-7890

3. 実行

python -m ads_mcp.server

Claude Code の設定

プロジェクトのルートに .mcp.json を配置します。

{
  "mcpServers": {
    "google-ads": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "ads_mcp.server"],
      "env": {
        "GOOGLE_ADS_CREDENTIALS": "${GOOGLE_ADS_CREDENTIALS}",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "${GOOGLE_ADS_LOGIN_CUSTOMER_ID}"
      }
    }
  }
}

Claude Code は .mcp.json を自動検出し、起動時にサーバーを読み込みます。

Claude Desktop の設定

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "google-ads": {
      "command": "python",
      "args": ["-m", "ads_mcp.server"],
      "env": {
        "GOOGLE_ADS_CREDENTIALS": "/path/to/google-ads.yaml",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "123-456-7890"
      }
    }
  }
}

利用可能なツール（29）

読み取りツール（9）

ツール	説明
list_accessible_customers	アクセス可能なすべての顧客アカウントを一覧表示します
list_accounts	MCC 配下のアカウントを詳細とともに一覧表示します
execute_gaql	カスタム GAQL クエリを実行します
get_campaign_performance	期間を指定してキャンペーンの指標を取得します
get_keyword_performance	キーワードの指標と品質スコアを取得します
get_search_terms	無駄な支出を含む検索語句レポートを取得します
get_ad_performance	広告クリエイティブのパフォーマンスを取得します
get_account_budget_summary	予算の使用状況を分析します
generate_keyword_ideas	キーワードプランナーの検索ボリュームと CPC を取得します

監査ツール（7）

ツール	説明
get_auction_insights	競合オークションデータを取得します
get_change_history	アカウントの最近の変更を取得します
get_device_performance	デバイスの種類別にパフォーマンスを取得します
get_geo_performance	地域別にパフォーマンスを取得します
get_recommendations	Google の最適化案を取得します
get_pmax_performance	Performance Max キャンペーンのデータを取得します
get_impression_share	インプレッション シェアと失われた機会を取得します

書き込みツール（11）— デフォルトではドライラン

ツール	説明
update_campaign_budget	1 日の予算を変更します
update_campaign_status	キャンペーンを一時停止または有効化します
update_ad_group_status	広告グループを一時停止または有効化します
update_keyword_bid	キーワードの CPC 入札単価を変更します
add_keywords	広告グループにキーワードを追加します
add_negative_keywords	除外キーワードを追加します
remove_negative_keyword	除外キーワードを削除します
create_campaign	新しいキャンペーンを作成します（一時停止状態）
create_ad_group	新しい広告グループを作成します
switch_bidding_strategy	入札戦略を変更します
generic_mutate	Google Ads API の直接的な変更処理を実行します

すべての書き込みツールでは、デフォルトで confirm=False（ドライランのプレビュー）が使用されます。プレビューを確認した後にのみ confirm=True を渡してください。

ドキュメントツール（2）

ツール	説明
get_gaql_reference	GAQL の構文とフィールドのリファレンス
get_workflow_guide	ワークフローの手順

認証情報の取得元

値	取得先
Developer Token	ads.google.com → Tools & Settings → API Center
Client ID	console.cloud.google.com → Credentials
Client Secret	console.cloud.google.com → Credentials
Refresh Token	OAuth Playground または google-ads Python 認証ヘルパー
Login Customer ID	ご利用の MCC アカウント ID（Google Ads UI の上部）

トラブルシューティング

問題	解決方法
UNAUTHENTICATED	リフレッシュトークンの期限切れです。OAuth Playground から再生成してください
PERMISSION_DENIED	お使いの MCC からアカウントにアクセスできません
DEVELOPER_TOKEN_NOT_APPROVED	ads.google.com → API Center で Basic Access を申請してください
レート制限を超過	Basic Access の上限は 1 日あたり 15K ops です。LIMIT 句とフィルターを使用してください

関連情報

• google-ads-mcp リポジトリ — ソースコード一式
• google-ads-api-agent — 28 個のツールを備えた Python エージェント
• googleadsagent.ai — 本番システム（Buddy）