ads-mcp

ads-mcp

Google Ads API と Meta Marketing API を直接ラップする MCP サーバーです。サードパーティのクォータや仲介業者はありません。MCP 対応クライアントから接続するだけで、Google と Meta の各 API を通じて、検索キャンペーン、キーワード、広告、および Meta キャンペーンのライフサイクル全体（作成、公開、監視、レポート）を管理できます。

費用が発生する可能性のある書き込みツールは、すべてデフォルトで安全に動作します。google_ads_create_search_campaign と Meta の作成／コピー用ツールは、常にオブジェクトを PAUSED 状態で作成します。費用の発生を有効にできるのは google_ads_set_campaign_status と meta_ads_set_campaign_status ／ meta_ads_set_ad_set_status ／ meta_ads_set_ad_status だけで、明示的に呼び出す必要があります。

セットアップ

認証情報には、本人しか持っていないログイン情報とビジネス上の本人確認情報が必要です。そのため、ここで自動化することはできません。.env をコミットしないでください。

Google Ads

1. Google Cloud プロジェクトと OAuth クライアント：console.cloud.google.com で新しい（または既存の）プロジェクトを選択し、API とサービス、認証情報の順に移動して、OAuth クライアント ID を作成します（種類：Desktop app）。クライアント ID／シークレットをコピーして .env に貼り付けます。
2. その OAuth クライアントで、http://localhost:8787/oauth2callback を承認済みのリダイレクト URI として追加します。
3. 開発者トークン：ads.google.com/aw/apicenter でトークンを申請します。基本アクセスは無料で、通常は数日以内に承認されます。1 日あたり約 15,000 回の操作が可能です。.env で GOOGLE_ADS_DEVELOPER_TOKEN として設定します。
4. pnpm install を実行してから pnpm google:auth を実行します。ブラウザーが開くので、ログインして同意すると、更新トークンが表示されます。これを .env に GOOGLE_ADS_REFRESH_TOKEN として貼り付けます。
5. これらのツールがデフォルトで操作する、10 桁のアカウント ID（ハイフンなし）を GOOGLE_ADS_CUSTOMER_ID に設定します。そのアカウントが MCC アカウントで管理されている場合は、MCC の ID も GOOGLE_ADS_LOGIN_CUSTOMER_ID に設定します。

Meta Ads（System User トークン）

個人ユーザーのトークンは、Facebook のログインチェックポイントが表示されると無効になります（Graph エラー 190／サブコード 459）。Business Manager の System User トークンを使うことが、個人のブラウザーセッションに依存せず Marketing API へのアクセスを維持するためにサポートされている方法です。

1. Meta アプリ：developers.facebook.com にアクセスし、My Apps から Create App を選択します（タイプ：Business）。Settings > Basic にある App ID と App Secret を .env に META_APP_ID／META_APP_SECRET としてコピーします。
2. Business Manager：business.facebook.com > Business Settings を開きます。
3. System User を作成する：Users > System Users > Add を選択します。広告アカウント、ページ、ピクセルを割り当てるには、Admin が最も簡単です。名前は ads-mcp のようにします。
4. アセットを System User に割り当てる（Add Assets）：
   • 広告アカウント：キャンペーンの管理を許可します（またはフルコントロール）。
   • クリエイティブで使用する Facebook ページ：コンテンツの作成／広告の管理を許可します（またはフルコントロール）。
   • 最適化に使用するピクセル：広告掲載を許可します。
5. トークンを生成する：System User で Generate New Token を選択します。手順 1 のアプリを選択し、少なくとも以下をリクエストします：
   • ads_management
   • ads_read
   • business_management
   • pages_show_list
   • pages_read_engagement
   • pages_manage_ads（未公開のページ投稿の作成／クリエイティブのリンクに必要です） UI に選択肢がある場合は、無期限のトークンを選択します。
6. トークンを .env に META_ACCESS_TOKEN として設定します。絶対にコミットしないでください。
7. META_AD_ACCOUNT_ID に数値のアカウント ID を設定します（act_ プレフィックスは任意です）。必要に応じて META_PAGE_ID と META_PIXEL_ID を設定すると、作成ツールで呼び出しのたびに指定する必要がなくなります。
8. 任意：META_GRAPH_API_VERSION を設定すると、Graph バージョンを固定できます。デフォルトは v26.0 です。

アプリレビュー／開発モード。 アプリ、広告アカウント、ページ、ピクセルがすべて同じ Business に属している場合、System User トークンは通常、アプリが開発モード（Standard Access）の状態でもアプリレビューなしで動作します。他の Business の広告アカウントを管理する場合、またはアプリが Live で該当の権限に制限がある場合は、Advanced Access とアプリレビューが必要です。ads_management と pages_* 権限は、Meta がレビュー対象とすることが最も多い権限です。

住宅、雇用、信用、および（一部地域における）金融商品・サービスの広告では、special_ad_categories を適切に設定する必要があります（HOUSING、EMPLOYMENT、CREDIT、FINANCIAL_PRODUCTS_SERVICES）。これらのキャンペーンには追加のターゲティング制限があり、カテゴリによっては Advantage+ が必須または禁止される場合があります。

最初に meta_ads_get_account を呼び出してください。META_APP_ID と META_APP_SECRET が設定されている場合、レスポンスにトークンのデバッグ情報（スコープ、有効期限）が含まれます。

このサーバーが書き換える Graph エラー

コード	よくある原因	対処方法
190 / 102	トークンの期限切れ、取り消し、または無効	System User トークンを新しく生成します
190 + サブコード 459、またはコード 459	ユーザーチェックポイント	Facebook のログインチェックポイントを完了してから、System User トークンに切り替えます
10、200-299	権限またはアセットの割り当てが不足	広告アカウント／ページ／ピクセルを割り当て、上記のスコープを追加します。Live または別の Business を対象とする場合はアプリレビューを受けます
100 + error_user_title / error_user_msg	無効なフィールド、または広告ポリシーによる却下	フィールドまたはクリエイティブを修正します。ポリシーによる却下は API で回避できません
4 / 17 / 32 / 613	レート制限	待ってから再試行します
368	一時的なポリシーによるブロック	Business Support Home とアカウントの Quality タブを確認します

実行

pnpm install
pnpm test
pnpm dev        # MCP server over stdio via tsx
pnpm build && pnpm start   # compiled version

npm に公開されると、npx @gudlab/ads-mcp でも実行でき、ローカルへのクローンは不要です。MCP 対応クライアントから接続します。たとえば、Claude Code の .mcp.json では次のように設定します：

{
  "mcpServers": {
    "ads-mcp": {
      "command": "npx",
      "args": ["-y", "@gudlab/ads-mcp"],
      "env": {
        "GOOGLE_ADS_CLIENT_ID": "...",
        "GOOGLE_ADS_CLIENT_SECRET": "...",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "...",
        "GOOGLE_ADS_REFRESH_TOKEN": "...",
        "GOOGLE_ADS_CUSTOMER_ID": "...",
        "META_APP_ID": "...",
        "META_APP_SECRET": "...",
        "META_ACCESS_TOKEN": "...",
        "META_AD_ACCOUNT_ID": "...",
        "META_PAGE_ID": "...",
        "META_PIXEL_ID": "..."
      }
    }
  }
}

公開前は、代わりにローカルビルドを指定します。command: "node"、args: ["/path/to/ads-mcp/dist/index.js"] を指定するか、ローカルで開発する場合は cwd をこのディレクトリに設定して command: "pnpm"、args: ["dev"] を指定します。

初回の実運用：信頼する前に検証する

Google Ads API と Meta Marketing API では、バージョンによってフィールド名や列挙値の名前が変わるため、実際のキャンペーン作業でこのツールを使う前に、次の手順を実行してください。

1. まず google_ads_list_campaigns / meta_ads_get_account / meta_ads_list_campaigns を読み取り専用で実行します。認証とクライアントライブラリの接続が正しく設定されているかを、最も低コストで確認できます。
2. google_ads_create_search_campaign または meta_ads_create_campaign を使い、使い捨ての名前でテストします。その後、ツールの応答を正しさの証拠として信頼するのではなく、広告 UI で確認してください。
3. その後に限り、実際のキャンペーンで *_set_*_status を ACTIVE にして使用します。

Meta のエンドツーエンド例（最後の手順まで常に一時停止状態）

予算の単位は広告アカウントの通貨です（例：20 は 20 GBP を意味し、Graph にはマイナー単位の 2000 として送信されます）。

1. meta_ads_get_account
     Confirm the token is valid and the account currency / timezone.

2. meta_ads_search_targeting
     { "q": "online shopping", "type": "interest" }
     Copy an interest id from the results. Some detailed interests have been retired by Meta; try a broader query or type=behavior if this is empty.

3. meta_ads_estimate_audience
     { "targeting": { "countries": ["GB"], "age_min": 25, "age_max": 54, "interests": [{ "id": "6003139266461" }] },
       "optimization_goal": "OFFSITE_CONVERSIONS" }

4. meta_ads_create_campaign
     { "name": "UK leads - paused",
       "objective": "OUTCOME_LEADS",
       "special_ad_categories": [] }
     Returns campaign_id. Status is PAUSED.

5. meta_ads_create_ad_set
     { "campaign_id": "<campaign_id>",
       "name": "GB 25-54 shopping",
       "daily_budget": 15,
       "optimization_goal": "OFFSITE_CONVERSIONS",
       "billing_event": "IMPRESSIONS",
       "custom_event_type": "COMPLETE_REGISTRATION",
       "advantage_audience": false,
       "targeting": {
         "countries": ["GB"],
         "age_min": 25,
         "age_max": 54,
         "interests": [{ "id": "6003139266461", "name": "Online shopping" }]
       } }
     Advantage+ audience is off (`targeting_automation.advantage_audience = 0`). Status is PAUSED.

6. meta_ads_upload_image
     { "url": "https://example.com/ads/hero.jpg" }
     or { "path": "/absolute/path/hero.jpg" }
     Returns hash.

7. meta_ads_create_ad_creative
     { "name": "Homepage v1",
       "link": "https://example.com/?utm_source=meta",
       "message": "Open an account from your banking app.",
       "headline": "Pay from your bank",
       "description": "No card needed.",
       "image_hash": "<hash>",
       "cta_type": "LEARN_MORE",
       "url_tags": "utm_source=meta&utm_medium=paid&utm_campaign=uk_leads" }

8. meta_ads_create_ad
     { "name": "Ad 1", "ad_set_id": "<ad_set_id>", "creative_id": "<creative_id>" }
     Status is PAUSED. Still no spend.

9. Activate spend, in this order (or campaign last):
     meta_ads_set_ad_status          { "ad_id": "<ad_id>", "status": "ACTIVE" }
     meta_ads_set_ad_set_status      { "ad_set_id": "<ad_set_id>", "status": "ACTIVE" }
     meta_ads_set_campaign_status    { "campaign_id": "<campaign_id>", "status": "ACTIVE" }

10. meta_ads_get_ad_status
      Review / rejection lives in ad_review_feedback and issues_info.

11. meta_ads_get_insights
      { "level": "campaign", "object_id": "<campaign_id>", "date_preset": "last_7d" }
      Optional: "breakdowns": ["age", "gender", "placement", "day"]
      or "since": "2026-10-01", "until": "2026-10-07"

ツールリファレンス

Google Ads（src/google-ads/tools.ts）：list_campaigns、get_campaign_structure、create_search_campaign（常に PAUSED）、add_keywords、set_keyword_status（一時停止／有効化、元に戻せます）、remove_keywords（完全に削除され、confirm_delete: true が必要です）、update_bid_strategy、add_negative_keywords、set_campaign_status（有効化／費用発生を切り替える唯一のツールです）。

Meta Ads（src/meta-ads/tools.ts）、すべての名前に meta_ads_ が付きます。

ツール	役割
get_account	広告アカウント＋任意のトークンデバッグ
list_campaigns / get_campaign / get_campaign_structure	キャンペーン、ネストされた広告セットと広告
list_ad_sets / get_ad_set	ターゲティング、予算、Advantage+ フラグを含む広告セット
list_ads / get_ad / get_ad_status / list_ads_by_status	広告、クリエイティブ、ad_review_feedback / issues_info
get_insights	アカウント／キャンペーン／広告セット／広告の指標、プリセットまたはカスタム日付、任意の内訳
search_targeting	興味・関心、行動、地域のキーワード検索
estimate_audience	配信／リーチの推定
create_campaign / update_campaign	目的、special_ad_categories、キャンペーンまたは広告セットの予算。作成時は PAUSED
create_ad_set / update_ad_set	1 日の予算、最適化、ピクセル＋イベント、手動ターゲティング。デフォルトでは Advantage+ はオフ。作成時は PAUSED
upload_image	ローカルパスまたは URL → 画像ハッシュ
create_ad_creative	ページ、リンク、メインテキスト、見出し、説明、CTA、url_tags
create_ad / update_ad	クリエイティブの添付またはコピーの置き換え。作成時は PAUSED
set_campaign_status / set_ad_set_status / set_ad_status	ACTIVE / PAUSED を明示的に設定。費用発生を切り替える唯一のツール
copy_campaign / copy_ad_set / copy_ad	複製。常に PAUSED

プライバシーとデータの取り扱い

すべての認証情報は、独自の .env（コミットされません。.gitignore を参照）または MCP クライアント独自の環境設定に保持され、マシンから Google と Meta の API を直接呼び出すためにのみ使用されます。このサーバーは、テレメトリー、アナリティクス、リレーサービスを含め、第三者に何も送信しません。すべてのリクエストは、独自の開発者トークンとアクセストークンを使用して、プロセスから googleads.googleapis.com または graph.facebook.com に直接送信されます。

ライセンス

MIT。詳しくは LICENSE を参照してください。