Google Ad Manager MCP

Google Ad Manager MCP サーバー

AI で Google Ad Manager を自動化できます。 Claude、ChatGPT、Gemini、Cursor、VS Code などの AI アシスタントが、自然言語で広告キャンペーン、広告申込情報、クリエイティブなどを管理できる MCP サーバーです。

Matious が開発 — ビジネス向けのカスタム AI ツールと MCP サーバーを開発しています。

---

このプロジェクトを開発した理由

Google Ad Manager の管理には手間がかかります。複雑な UI を何度もクリックして、キャンペーンの作成、クリエイティブのアップロード、広告申込情報の設定を行う必要があります。

この MCP サーバーがその作業を変えます。 Claude に接続すれば、会話を通じて広告運用全体を管理できます。

• 「Nike の新しいキャンペーンを作成して。終了日は 12 月 31 日にして」
• 「このフォルダー内のすべてのクリエイティブをアップロードして、Display の広告申込情報に関連付けて」
• 「現在配信中の受注を確認して」

もうクリック操作は不要です。必要なことを Claude に伝えるだけです。

機能

• 受注管理：受注の一覧表示、作成、管理
• 広告申込情報の管理：広告申込情報の作成、複製、設定
• クリエイティブ管理：画像のアップロード、広告申込情報との関連付け、一括アップロード
• 広告主管理：広告主の検索、作成、一覧表示
• 確認ツール：広告申込情報の設定確認、配信状況の確認
• キャンペーンのワークフロー：1 回の操作でキャンペーンを作成

インストール

PyPI から（推奨）

pip install google-ad-manager-mcp

または uv を使用します。

uv pip install google-ad-manager-mcp

ソースから

git clone https://github.com/MatiousCorp/google-ad-manager-mcp.git
cd google-ad-manager-mcp
pip install -e .

依存関係

• FastMCP：ネイティブのミドルウェアをサポートする MCP サーバーフレームワーク
• googleads：Google Ad Manager SOAP API クライアント

設定

サーバーの設定には環境変数を使用します。

変数	説明	必須
GAM_CREDENTIALS_PATH	サービスアカウント JSON のパス	はい
GAM_NETWORK_CODES	GAM ネットワークコードのカンマ区切りリスト（先頭がデフォルト）	はい
GAM_MCP_TRANSPORT	トランスポートモード：stdio または http	いいえ（デフォルト：stdio）
GAM_MCP_HOST	サーバーホスト（HTTP モードのみ）	いいえ（デフォルト：0.0.0.0）
GAM_MCP_PORT	サーバーポート（HTTP モードのみ）	いいえ（デフォルト：8000）
GAM_MCP_AUTH_TOKEN	認証トークン（HTTP モードのみ）	いいえ（未設定の場合は自動生成）

複数ネットワークのサポート

1 つのサーバーインスタンスで複数の GAM ネットワークを管理できます。すべてのネットワークコードを GAM_NETWORK_CODES に記載してください。先頭のコードがデフォルトになります。

export GAM_NETWORK_CODES="31083078,22706375620,98765432"

すべてのツールで省略可能な network_code パラメーターを使用できます。省略すると、先頭の（デフォルトの）ネットワークが使用されます。すべてのネットワークで同じサービスアカウント認証情報が共有されます。サービスアカウントのメールアドレスが各ネットワークのユーザーとして追加されていることを確認してください。

Claude Code の MCP 設定：

{
  "google-ad-manager": {
    "command": "uvx",
    "args": ["google-ad-manager-mcp"],
    "env": {
      "GAM_CREDENTIALS_PATH": "/path/to/credentials.json",
      "GAM_NETWORK_CODES": "31083078,22706375620"
    }
  }
}

認証

このサーバーは、MCP セキュリティのベストプラクティスに従い、FastMCP のネイティブミドルウェアを使用した Bearer トークン認証を実装しています。

セキュリティ機能

• FastMCP ネイティブミドルウェア：FastMCP 2.x ミドルウェアを使用し、MCP のライフサイクルを適切に管理
• 暗号学的に安全なトークン：secrets.token_hex(32) を使用して生成
• タイミング攻撃の防止：時間に依存しない比較（hmac.compare_digest）を使用
• ツールレベルの認証：すべてのツール呼び出しで認証を検証
• 監査ログ：すべての認証失敗を記録

仕組み

FastMCP のミドルウェアシステムを使用して、ツールレベルで認証を適用します。

• ツールが呼び出されると、ミドルウェアが Authorization ヘッダーを検証します
• トークンが設定されていない場合（GAM_MCP_AUTH_TOKEN が未設定の場合）、リクエストは許可されます
• 無効なトークンまたはトークンがない場合は、わかりやすいメッセージとともに ToolError が返されます

セットアップ

リモート環境にデプロイする場合は、固定の認証トークンを設定します。

# Generate a secure token
python -c "import secrets; print(secrets.token_hex(32))"

# Set it as environment variable
export GAM_MCP_AUTH_TOKEN="your-generated-token"

設定されていない場合は、起動時にランダムなトークンが生成され、ログに表示されます。

クライアントは Authorization ヘッダーにトークンを含める必要があります。

Authorization: Bearer your-generated-token

エンドポイント

エンドポイント	説明
/mcp	MCP プロトコルのエンドポイント（ツール呼び出し時に認証を検証）

サーバーの実行

ローカル開発

# Using the installed command
gam-mcp

# Or directly with Python
python -m gam_mcp.server

# With custom configuration
GAM_NETWORK_CODE=12345678 GAM_MCP_PORT=9000 gam-mcp

Docker でのデプロイ

Docker イメージは、セキュリティのため非 root ユーザー（appuser）として実行されます。

イメージのビルド

docker build -t google-ad-manager-mcp .

コンテナの実行

# Basic usage with credentials mounted
docker run -d \
  --name gam-mcp \
  -p 8000:8000 \
  -v /path/to/your/credentials.json:/app/credentials.json:ro \
  -e GAM_NETWORK_CODE=YOUR_NETWORK_CODE \
  google-ad-manager-mcp

# With authentication token (recommended for production)
docker run -d \
  --name gam-mcp \
  -p 8000:8000 \
  -v /path/to/your/credentials.json:/app/credentials.json:ro \
  -e GAM_NETWORK_CODE=YOUR_NETWORK_CODE \
  -e GAM_MCP_AUTH_TOKEN=$(python -c "import secrets; print(secrets.token_hex(32))") \
  google-ad-manager-mcp

# With custom port
docker run -d \
  --name gam-mcp \
  -p 9000:8000 \
  -v /path/to/your/credentials.json:/app/credentials.json:ro \
  -e GAM_NETWORK_CODE=YOUR_NETWORK_CODE \
  -e GAM_MCP_PORT=8000 \
  google-ad-manager-mcp

ログの表示

# View startup logs (includes generated auth token if not set)
docker logs gam-mcp

# Follow logs
docker logs -f gam-mcp

Docker Compose

docker-compose.yml ファイルを作成します。

version: '3.8'
services:
  gam-mcp:
    build: .
    ports:
      - "8000:8000"
    volumes:
      - ./credentials.json:/app/credentials.json:ro
    environment:
      - GAM_NETWORK_CODE=YOUR_NETWORK_CODE
      - GAM_MCP_AUTH_TOKEN=your-secure-token
    restart: unless-stopped

次のコマンドで実行します。

docker-compose up -d

コンテナの確認

# Check container is running
docker ps

# Test the endpoint
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0"}}, "id": 1}'

クラウドへのデプロイ（Railway、Fly.io など）

1. クラウドプロバイダーで環境変数を設定します。

   • GAM_CREDENTIALS_PATH：認証情報へのパス（またはシークレットを使用）
   • GAM_NETWORK_CODE：Ad Manager のネットワークコード
   • GAM_MCP_AUTH_TOKEN：安全な認証トークン

2. 同梱の Dockerfile を使用してデプロイします

AI アシスタントへの接続

Claude Desktop（uvx - 推奨）

Claude Desktop でこのサーバーを使用する最も簡単な方法です。~/Library/Application Support/Claude/claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "google-ad-manager": {
      "command": "uvx",
      "args": ["google-ad-manager-mcp"],
      "env": {
        "GAM_CREDENTIALS_PATH": "/path/to/your/credentials.json",
        "GAM_NETWORK_CODE": "YOUR_NETWORK_CODE"
      }
    }
  }
}

Claude Desktop（Docker）

~/Library/Application Support/Claude/claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "google-ad-manager": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GAM_NETWORK_CODE",
        "-v", "/path/to/credentials.json:/app/credentials.json:ro",
        "google-ad-manager-mcp"
      ],
      "env": {
        "GAM_NETWORK_CODE": "YOUR_NETWORK_CODE"
      }
    }
  }
}

Claude Desktop（HTTP モード）

サーバーを HTTP モードで実行する場合：

{
  "mcpServers": {
    "google-ad-manager": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

認証付きリモートサーバー

認証を有効にしてリモート環境にデプロイする場合：

{
  "mcpServers": {
    "google-ad-manager": {
      "url": "https://your-server.com/mcp",
      "headers": {
        "Authorization": "Bearer your-secure-token"
      }
    }
  }
}

その他の MCP クライアント

このサーバーは、以下を含む、MCP 対応のあらゆるクライアントで動作します。

• ChatGPT Desktop - OpenAI は 2025 年 3 月に MCP を採用しました
• Cursor - MCP に対応した AI 搭載 IDE
• VS Code - MCP 拡張機能を使用
• Windsurf、Zed、Codeium - 各種 IDE 統合

MCP サーバーの設定については、各クライアントのドキュメントを参照してください。

MCP Inspector でのテスト

# Without authentication
npx @modelcontextprotocol/inspector http://localhost:8000/mcp

# With authentication (set header in Inspector UI)
# Header: Authorization
# Value: Bearer your-token

利用可能なツール

注文ツール

ツール	説明
list_delivering_orders	配信中のラインアイテムがあるすべての注文を一覧表示
get_order	ID または名前で注文の詳細を取得
create_order	新しい注文を作成
find_or_create_order	既存の注文を検索するか、新しい注文を作成

ラインアイテムツール

ツール	説明
get_line_item	ラインアイテムの詳細を取得
create_line_item	新しいラインアイテムを作成
duplicate_line_item	既存のラインアイテムを複製
update_line_item	ラインアイテムのプロパティ（名前、種類、配信率、優先度、費用、目標、終了日）を更新
list_line_items_by_order	注文のすべてのラインアイテムを一覧表示
pause_line_item	配信中のラインアイテムを一時停止
resume_line_item	一時停止中のラインアイテムを再開
archive_line_item	ラインアイテムをアーカイブ
approve_line_item	ラインアイテムを承認（承認ワークフロー用）

クリエイティブツール

ツール	説明
upload_creative	画像クリエイティブをアップロード
associate_creative_with_line_item	クリエイティブをラインアイテムに関連付け
upload_and_associate_creative	1 回の操作でアップロードと関連付けを実行
bulk_upload_creatives	フォルダー内のすべてのクリエイティブをアップロード
get_creative	クリエイティブの詳細を取得
list_creatives_by_advertiser	広告主のクリエイティブを一覧表示
update_creative	クリエイティブのリンク先 URL または名前を更新
list_creatives_by_line_item	ラインアイテムに関連付けられたクリエイティブを一覧表示
create_third_party_creative	HTML/JavaScript 広告タグ（DCM、カスタム HTML）を作成
get_creative_preview_url	サイト上でクリエイティブを確認するためのプレビュー URL を生成

広告主ツール

ツール	説明
find_advertiser	名前で広告主を検索します
get_advertiser	広告主の詳細を取得します
list_advertisers	すべての広告主を一覧表示します
create_advertiser	新しい広告主を作成します
find_or_create_advertiser	広告主を検索または作成します

検証ツール

ツール	説明
verify_line_item_setup	ラインアイテムの設定を検証します
check_line_item_delivery_status	配信状況を確認します
verify_order_setup	注文全体の設定を検証します

レポートツール

ツール	説明
run_delivery_report	配信レポートを生成します（インプレッション数、クリック数、CTR、収益）
run_inventory_report	在庫レポートを生成します（広告リクエスト数、フィル率）
run_custom_report	指定したディメンションと指標を使ってカスタムレポートを生成します

ワークフローツール

ツール	説明
create_campaign	キャンペーン作成ワークフロー全体を実行します

Claude での使用例

User: List all delivering orders

Claude: [Uses list_delivering_orders tool]
Here are the currently delivering orders:
1. Campaign IPhone 17 Pro 2025/2026 (ID: 123456)
   - Display line item: 45,000 impressions delivered

User: Create a new campaign for "ACME Corp" ending December 31, 2025

Claude: [Uses create_campaign tool]
I'll create the campaign with:
- Advertiser: ACME Corp
- Order: ACME Campaign 2025
- Line Item: Display
- End Date: December 31, 2025

Campaign created successfully!
- Order ID: 789012
- Line Item ID: 345678
- 4 creatives uploaded and associated

開発

セットアップ

# Clone the repository
git clone https://github.com/MatiousCorp/google-ad-manager-mcp.git
cd google-ad-manager-mcp

# Install with dev dependencies
pip install -e ".[dev]"

テストの実行

# Run all tests
pytest

# Run with coverage
pytest --cov=gam_mcp --cov-report=html

# Run specific test file
pytest tests/test_utils.py

コード品質

# Run linter
ruff check .

# Run linter with auto-fix
ruff check . --fix

ロードマップ

今後のリリースでは、以下の機能を予定しています。

短期

• 広告ユニット管理 - 階層構造に対応した広告ユニットの一覧表示、取得、作成
• プレースメント管理 - 在庫プレースメントとターゲティングを管理
• 予測と利用可能状況 - 在庫の利用可能状況を確認し、インプレッション数を予測
• クリエイティブプレビューリンク - クリエイティブとラインアイテムの組み合わせのプレビュー URL を生成

中期

• 高度なターゲティング - 地域、デバイス、時間帯、カスタムキー値によるターゲティング
• レポートツール - パフォーマンスレポートを生成、取得
• 一括操作 - ラインアイテム、クリエイティブ、ターゲティングの一括更新
• HTML5／動画クリエイティブ - リッチメディアと動画クリエイティブのアップロードに対応

長期

• オーディエンス管理 - オーディエンスセグメントを作成、管理
• ユーザーと権限 - ユーザー、ロール、注文の割り当てを管理
• イールド管理 - イールドグループと最適化を設定
• カスタムレポート - エクスポート機能付きのスケジュールレポート

コミュニティからのリクエスト

機能の追加をお望みですか？新しい機能を提案するには、イシューを作成してください。

コントリビューション

コントリビューションを歓迎します！ガイドラインについては、CONTRIBUTING.mdをご覧ください。

変更履歴

バージョン履歴については、CHANGELOG.mdをご覧ください。

API バージョン

Google Ad Manager SOAP API バージョン v202502 を使用します。

ライセンス

MIT - 詳細はLICENSEをご覧ください。

---

カスタム MCP サーバーが必要ですか？

このプロジェクトは**Matious**が構築、保守しています。

既存のシステムと連携するカスタム AI ツールと MCP サーバーの構築を専門としています。Claude を CRM、ERP、広告プラットフォーム、社内ツールに接続する必要がある場合は、お手伝いします。

提供内容：

• あらゆる API やプラットフォーム向けのカスタム MCP サーバー
• AI を活用した自動化ワークフロー
• 業務向け Claude 連携

お問い合わせ： matious.com