gadschain

GadsChain

Google Ads アカウントとマーケティング上の意思決定をつなぐ AI レイヤーです。

実戦で検証済みです。 6 つのツールで、キャンペーンの一覧表示、検索語句の確認、予算の調整、一時停止／有効化、除外キーワードの整理という日々の運用サイクルをカバーします。すべての応答は厳格な Pydantic モデルです。生の protobuf がエージェントに渡ることはありません。

☁️ 本番環境への移行をお考えですか？

オープンソースのサーバーは、ご自身の API キーを使ってローカルで実行できます。 複数アカウントのフェイルオーバー、SLA 保証、 Webhook アラートを備えたホスト型インフラについては、マネージドクラウドのウェイトリストにご登録ください。

課題

Google Ads API の生データは、数千行を返します。不適切なキャンペーン構成が 1 つあるだけで、気づかないうちに予算が浪費されます。GadsChain は広告データを読み取り、サニタイズしてから処理するため、無駄が積み重なるのを防げます。

インストール

git clone https://github.com/SnipMCP/gadschain.git
cd gadschain
pip install -e ".[dev]"
cp .env.example .env

または Docker を使用します。

docker-compose up --build

設定

GOOGLE_ADS_DEVELOPER_TOKEN=your_developer_token_here
GOOGLE_ADS_CLIENT_ID=your_oauth_client_id_here
GOOGLE_ADS_CLIENT_SECRET=your_oauth_client_secret_here
GOOGLE_ADS_REFRESH_TOKEN=your_refresh_token_here
GOOGLE_ADS_LOGIN_CUSTOMER_ID=1234567890   # MCC (manager), digits only
GOOGLE_ADS_CUSTOMER_ID=1234567890         # default operating account
GOOGLE_ADS_API_VERSION=v24
LOG_LEVEL=INFO

使い方

Claude（または MCP 対応エージェント）に送信するプロンプトの例を 3 つ紹介します。

1. Use get_campaigns to show me which campaigns are bleeding budget this month
2. Run get_search_terms for the last 30 days and tell me which queries are wasting spend
3. Add "free", "cheap", "jobs" as negative keywords to campaign 12345

2 つのターミナルで実行する

# Tab 1 — start the MCP server
python -m gadschain.server

# Tab 2 — call a tool from a Python shell or your MCP client
# Tool signatures:
#   get_campaigns(customer_id=None)
#   get_search_terms(customer_id=None, days=30, campaign_id=None)
#   update_budget(campaign_id, new_budget_dollars, customer_id=None)
#   pause_campaign(campaign_id, customer_id=None)
#   enable_campaign(campaign_id, customer_id=None)
#   add_negative_keywords(campaign_id, keywords, match_type="BROAD", customer_id=None)

仕組み

Google Ads の生データとモデルの間にある 3 つのレイヤーです。

Google Ads API → [Fetch] → [Transform] → [Act] → MCP Tool → AI Agent
                  GAQL      micros→$       safe
                  queries   enum→str       mutations
                            CTR→%          shared-budget guard

• 取得：対象を絞った GAQL クエリを使用し、日々の運用サイクルで実際に必要な列だけを取得します。SELECT * は使用せず、protobuf のページネーションに伴う落とし穴もありません。
• 変換：通貨のマイクロ単位をドルに換算し、CTR をパーセントに変換し、列挙値を人が読める文字列に変換します。ネストされた属性の参照はすべて、フィールドが欠落していてもクラッシュしないように処理されます。
• 実行：変更処理はガードレールを介して行われます。ステータス変更時の REMOVED はブロックされ、共有予算は拒否され（shared_budget_refused）、変更処理を呼び出す前にマッチタイプが検証されます。エージェントに例外が渡ることはありません。代わりに、推論可能な構造化データ {"error": ..., "message": ...} が返されます。

稼働中の Fr anka Pizzeria アカウントでの実測値（28 日間）

RAW GOOGLE ADS PAYLOAD          GADSCHAIN OUTPUT
─────────────────────────────────────────────────
Impressions:    3,389           Spend (28d):      $51.41
Clicks:         163             Conversions:      3 ($17.14 each)
CTR:            4.81%           Conv. rate:       1.84%
Cost/click:     $0.32 avg       Surface:          Display Network waste
                                                  identified on Fridays
                                                  ($0.11 CPC vs $0.44 avg)

実際のアカウントを一度確認したところ、GadsChain は28 日間で 51.41 ドルを費やし、コンバージョン 3 件を 1 件あたり 17.14 ドルで獲得したことを明らかにしました。紙面上では健全に見える CTR 4.81％の裏に、コンバージョン率 1.84％が隠れていました。ひそかな原因はディスプレイ ネットワークでした。金曜日のクリック単価は平均 0.11 ドルで、検索側の平均 0.44 ドルを下回っていました。安価で質の低いトラフィックが CTR を押し上げる一方で、コンバージョンには何も貢献していませんでした。変換後のペイロードによって、protobuf の中に埋もれていたチャネル別の成果が読み取れるようになったため、エージェントはこの問題を把握できました。

ロードマップ

• マネージドクラウドプラン（ホスト型、マルチテナント、Webhook アラート）
• フェーズ 2：ChatGPT REST shim（同じ 6 つのツールを提供する FastAPI インターフェース）
• 入札戦略の調整ツール（目標 CPA、目標 ROAS）
• コンバージョン単価の変動に関する異常アラート

貢献

PR を歓迎します。提出前に pytest を実行してください。