Meta Ads Mcp Scaleforge

ScaleForge の Meta Ads MCP

Claude、ChatGPT、Cursor、その他の MCP 互換エージェントから Facebook と Instagram の広告を管理できます。

Meta Graph API v24.0 の直接ラッパーです。32 個のツールを備えています。バックエンドは不要です。Meta アクセストークンをご用意ください。

---

課題

Meta の Marketing API は強力ですが、扱いが困難です。Meta Ads の自動化を試したことがある人なら、次の 5 つの壁に直面したことがあるでしょう。

1. レート制限とのいたちごっこ（エラーコード #17）。 スクリプトがローンチの途中で User request limit reached に遭遇し、キャンペーンが半端な設定のまま残ってしまいます。Meta のアカウントごとの呼び出し予算は 5 分ごとにリセットされますが、API は状況を把握していないとそのことを教えてくれません。
2. トークンの有効期限切れによる混乱。 Graph API Explorer のユーザーアクセストークンは、約 2 時間で期限切れになります。バグを修正して昼食から戻ると、すべてのリクエストが突然 (#190) Error validating access token になります。
3. v22 から v24 への非推奨化（2025 年 9 月）。 instagram_actor_id は instagram_user_id に変更され、degrees_of_freedom_spec は完全に廃止され、asset_feed_id は v3.1 以降非推奨です。Stack Overflow からコピーしたサンプルコードは、気づかないうちに動かなくなります。
4. 画像ハッシュは広告アカウントごとに異なります。 アカウント A にアップロードした画像はアカウント B では使えず、2 つ目のアカウントで Image Not Found が返されます。動画 ID はグローバルですが、画像ハッシュはそうではありません。初めて複数アカウントの自動化を行う人は、誰もがこの問題に直面します。
5. 1 ページあたり 250 件の広告上限。 Meta はアカウントごとではなくページごとに、配信中または審査中の広告数を制限しています。この上限は、そのページを使用するすべてのアカウントで共有されます。上限を超えると、251 件目の広告は審査に失敗しても通知されません。

解決策

この MCP は Meta Graph API の薄い型付きラッパーで、上記 5 つの問題に対処します。

• 一括操作の自動バッチ処理（pause_campaigns_batch、activate_campaigns_batch、update_bids_batch）— 1 回の HTTP リクエストで最大 50 件の操作を実行し、自動的にチャンク分割します。一括処理でレート制限コード #17 を回避できます。
• 一括有効化の前に ads_volume を事前確認 — Meta で審査が通知なく失敗する前に、広告アカウントごとにページが 250 件の広告上限に近づいている場合は警告します。
• 実行可能なリンクを含む、強化されたエラーメッセージ — トークンの期限切れやレート制限が発生すると、MCP がエージェントに具体的な対処方法（システムユーザートークンの作成、5 分待つなど）を伝えます。
• すべて v24.0 に対応 — 現行のフィールド名を使用し、非推奨の仕様形式は使いません。
• PBIA の自動プロビジョニング（get_pbia）— ページにリンク済みの Instagram アカウントがない場合、MCP が必要に応じて Page-Backed Instagram Account を作成し、Instagram の配置が機能するようにします。

ScaleForge のバックエンドは経由しません。エージェント → この MCP → https://graph.facebook.com/v24.0/*。以上です。

---

ホスト型エンドポイント（インストール不要）

ScaleForge がホストする Streamable HTTP エンドポイントを使用できます。インストールも、ローカルでの実行も不要です。

• Smithery の掲載ページ： https://smithery.ai/server/kirichyk-misha/meta-ads（Claude Desktop、Cursor、Windsurf、Continue、ChatGPT Desktop にワンクリックでインストールできます。Smithery が Meta トークンを求め、設定を書き込みます）。
• カスタムクライアント向けの直接 URL：https://getscaleforge.com/mcp（MCP Streamable HTTP）。Smithery のセッション設定、または Authorization: Bearer <token> ヘッダーでトークンを指定してください。

ローカルに npm パッケージをインストールする場合は、以下の stdio パッケージを使用してください。

---

クイックスタート — いずれかを選択

Smithery（最も簡単。クライアントを自動設定）

npx -y @smithery/cli install @getscaleforge/mcp-meta-ads --client claude
# also: --client cursor | --client windsurf | --client continue

Smithery が Meta アクセストークンを求め、設定ファイルを書き込みます。

Claude Code CLI

claude mcp add scaleforge \
  --env META_ACCESS_TOKEN=YOUR_TOKEN \
  -- npx -y @getscaleforge/mcp-meta-ads

claude mcp list で確認してください。

Claude Desktop（JSON 設定を手動で編集）

macOS では ~/Library/Application Support/Claude/claude_desktop_config.json を編集します（Windows／Linux では同等の場所にあります。存在しない場合は Claude Desktop が作成します）。

{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": ["-y", "@getscaleforge/mcp-meta-ads"],
      "env": {
        "META_ACCESS_TOKEN": "YOUR_TOKEN_HERE"
      }
    }
  }
}

Claude Desktop を再起動してください。ハンマーアイコンの下に 32 個のツールが表示されます。

Cursor

プロジェクト内（またはグローバルに ~/.cursor/mcp.json）に .cursor/mcp.json を作成します：

{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": ["-y", "@getscaleforge/mcp-meta-ads"],
      "env": { "META_ACCESS_TOKEN": "YOUR_TOKEN_HERE" }
    }
  }
}

ローカルテスト（クライアントの設定不要）

META_ACCESS_TOKEN=YOUR_TOKEN npx -y @getscaleforge/mcp-meta-ads

サーバーは stdio で起動します。@modelcontextprotocol/inspector を使って対話的にテストできます：

npx -y @modelcontextprotocol/inspector \
  env META_ACCESS_TOKEN=YOUR_TOKEN npx -y @getscaleforge/mcp-meta-ads

---

アーキテクチャ

┌──────────────┐       MCP stdio        ┌───────────────────┐    HTTPS + OAuth token    ┌──────────────────────┐
│ Claude / GPT │ ◄────────────────────► │  mcp-meta-ads     │ ◄───────────────────────► │  Meta Graph API v24  │
│   Cursor     │   JSON-RPC over stdio  │  (this package)   │   graph.facebook.com      │  Marketing API       │
│ ChatGPT Desk │                        │                   │                           │                      │
└──────────────┘                        └───────────────────┘                           └──────────────────────┘

MCP は、型付けされた薄い翻訳レイヤーです。キャッシュもプロキシも行わず、外部にデータを送信することもありません。すべての呼び出しは、お使いのマシンからトークンを使って Meta のサーバーに直接送信されます。

---

Meta アクセストークンの取得

ads_management、ads_read、business_management の権限を持つアクセストークンが必要です。また、ページにスコープを限定した操作（PBIA のプロビジョニングなど）には、pages_read_engagement と pages_manage_ads も必要です。

トークンには 2 種類あります。用途に応じて選択してください。

オプション 1 — クイックトークン（2 分で取得、有効期限は約 2 時間）

用途：MCP の試用、簡単な実験、一度限りのスクリプト。

1. Graph API Explorer を開きます。
2. User or Page ドロップダウンで User Token を選択します。
3. Add a Permission をクリックし、ads_management、ads_read、business_management、pages_read_engagement、pages_manage_ads を選択します。
4. Generate Access Token をクリックし、ダイアログで承認します。
5. 上部に表示されたトークンをコピーします。これが META_ACCESS_TOKEN です。

トークンの有効期限は約 2 時間です。期限が切れると、MCP はこのページを案内する詳細なエラーを返します。

オプション 2 — 安定したトークン（有効期限なし）

用途：本番環境、定期実行ジョブ、2 時間ごとの再認証を避けたい場合。

Meta Business Manager 内で System User トークンを生成します。System User トークンには有効期限がなく、特定のアセット（広告アカウントとページ）にスコープを設定できます。ScaleForge をはじめ、本番環境の Meta 統合で使われているのと同じ種類のトークンです。

1. developers.facebook.com/apps で Facebook アプリを作成します（まだない場合）。どのアプリでも使えます。Business タイプで問題ありません。
2. business.facebook.com で Business Manager を作成します。System User のコンテナーとして必要です。
3. Business Settings → Accounts → Ad Accounts / Pages で、広告アカウントとページを Business に追加します。（別の Business が所有している場合は、アクセスをリクエストしてください。）
4. System User を作成します： Business Settings → Users → System Users → Add → 名前を入力します（例：mcp-meta-ads）→ ロールに Admin を選択します。 [スクリーンショット：Business Settings → Users → System Users タブの「Add」ボタン]
5. 広告アカウントを System User に割り当てます： System User をクリック → Add Assets → Ad Accounts を選択 → 対象のアカウントを選択 → Manage 権限をオンにします。ページについても同じ手順を繰り返します。 [スクリーンショット：「Manage」トグルを強調表示した Add Assets ダイアログ]
6. トークンを生成します： Generate New Token をクリック → Facebook アプリを選択 → スコープを選択します：
   • ads_management
   • ads_read
   • business_management
   • pages_read_engagement
   • pages_manage_ads
   • read_insights（任意。一部のインサイトの内訳に必要） [スクリーンショット：スコープ一覧を表示した Generate Token ダイアログ]
7. Generate をクリックしてトークンをコピーします。有効期限はありません。シークレットマネージャー、環境変数、またはパスワードマネージャーに保管してください。

使用方法：

META_ACCESS_TOKEN=EAAB...your-token... npx -y @getscaleforge/mcp-meta-ads

後でトークンを取り消すか再生成すると、古いトークンはただちに使えなくなります。

---

組み込みの課題対策

Meta の課題	この MCP での対処方法
一括操作時のレート制限コード #17	pause_campaigns_batch、activate_campaigns_batch、update_bids_batch は Meta Batch API（1 リクエストあたり最大 50 件の操作）を使用し、操作を自動で分割して、各分割の間に 2 秒の間隔を設けます。
1 ページあたり 250 件の広告という非通知上限	get_ads_volume と activate_campaigns_batch 内の自動実行前チェックにより、Meta が審査を開始する前に警告がレスポンスに含まれます。
トークン期限切れエラー	enhanceMetaError がコード 190／102／104／463／467 を検出し、安定したトークンの設定を案内するメッセージを返します。
IG ログインなしでの Instagram 配置	get_pbia が Page-Backed Instagram Account を自動作成し、object_story_spec 用の instagram_user_id を返します。
v22 の非推奨化	instagram_user_id を使用し、degrees_of_freedom_spec と asset_feed_id は使用しません。
画像ハッシュのスコープ	upload_image と create_ad_creative のドキュメントで説明しています。ハッシュはアカウントごとに異なるため、対象アカウントごとに再アップロードする必要があります。（アカウントごとのキャッシュ処理は ScaleForge のバックエンドにあり、今後のリリースでここに追加される予定です。）

---

ツールリファレンス

10 カテゴリーにわたる32 個のツールです。

アカウント（3）

名前	用途
list_ad_accounts	トークンでアクセス可能な広告アカウントの一覧
get_ad_account	1 つのアカウントの詳細情報（ステータス、支出上限、残高）
get_ads_volume	ページごとの配信中の広告数、上限、残り枠（実行前チェック）

キャンペーン（5）

名前	用途
list_campaigns	ページネーション対応のキャンペーン一覧
get_campaign	ID で指定したキャンペーン 1 件
create_campaign	書き込み — 新しいキャンペーンを作成（デフォルトは PAUSED）
update_campaign	書き込み — 変更可能な任意のフィールドを更新
delete_campaign	書き込み — 完全に削除

広告セット（5）

名前	用途
list_adsets	ad_account_id または campaign_id で一覧表示
get_adset	ID で指定した広告セット 1 件
create_adset	書き込み — キャンペーン配下に広告セットを作成
update_adset	書き込み — ターゲティング、入札額、予算、ステータスを更新
delete_adset	書き込み — 完全に削除

広告（4）

名前	用途
list_ads	ad_account_id、adset_id、または campaign_id で一覧表示
get_ad	ID で指定した広告 1 件（クリエイティブ、問題、プレビューリンクを含む）
update_ad	書き込み — 名前やステータスの更新、クリエイティブの差し替え
delete_ad	書き込み — 完全に削除

クリエイティブ（4）

名前	用途
list_creatives	広告アカウント内のすべてのクリエイティブの一覧
get_creative	ID で指定したクリエイティブ 1 件
create_ad_creative	書き込み — object_story_spec による単一テキストのクリエイティブ
create_ad_creative_with_asset_feed	書き込み — asset_feed_spec によるダイナミック／複数テキストのクリエイティブ

メディア（2）

名前	用途
upload_video	書き込み — リモート URL 経由で動画をアップロード（video_id を返します）
upload_image	書き込み — リモート URL 経由で画像をアップロード（アカウントにスコープされた image_hash を返します）

インサイト（3）

名前	用途
get_campaign_insights	内訳を含むキャンペーンレベルの指標
get_adset_insights	広告セットレベルの指標
get_ad_insights	広告レベルの指標（クリエイティブの比較）

一括操作（3）

名前	用途
pause_campaigns_batch	書き込み（一括） — Batch API 経由で複数のキャンペーンを一時停止
activate_campaigns_batch	書き込み（一括） — 複数のキャンペーンを有効化し、実行前に ads_volume をチェック
update_bids_batch	書き込み（一括） — 複数の広告セットの bid_amount を更新

ページ（2）

名前	用途
list_pages	トークンで管理できる Facebook ページ
get_pbia	Page-Backed Instagram Account を取得または自動作成

広告ライブラリ（1）

名前	用途
search_ads_library	競合調査向けの Meta 広告ライブラリの公開検索

---

プロンプトの例

サーバーを接続したら、エージェントで次のプロンプトを試してみてください。

読み取り専用

• 「Meta の広告アカウントを一覧表示し、それぞれの有効状態、通貨、支出上限を教えてください。」
• 「キャンペーン 1234567890 の last_14d インサイトを、配置別の内訳で取得してください。CPL が最も低い配置はどれですか？」
• 「アカウント act_555 の ads_volume を表示してください。上限の 85% を超えているページはありますか？」
• 「Meta Ad Library で、過去 1 か月に米国で配信されている競合 X の広告を検索してください。」
• 「キャンペーン ABCD のすべての広告セットを一覧表示し、is_dynamic_creative=true のものを教えてください。」

書き込み（先に確認）

書き込み操作は Meta 広告の稼働状態を変更し、支出が直ちに開始または停止されます。適切に動作するエージェント（Claude、GPT-4）は、これらを呼び出す前に対象の一覧を表示し、「続行しますか？」と確認します。

• 「キャンペーン 111、222、333 を一時停止してください。まず名前と現在の支出を表示してから、一時停止してください。」
• 「キャンペーン 444 と 555 を有効にしてください。まず事前確認として ads_volume を実行し、85% を超えているページがあれば中止して、どのページか教えてください。」
• 「広告セット 6001 と 6002 の入札額を $4.50 に引き上げてください。セント単位に換算してください。」
• 「act_777 に、'Spring Promo Test' という名前で、OUTCOME_LEADS 目標、daily_budget 5000 セント、PAUSED の新しいキャンペーンを作成してください。」

---

FAQ

Meta アクセストークンを取得するにはどうすればよいですか？

上記の Meta アクセストークンを取得する を参照してください。方法は 2 つあります。短時間有効な 2 時間トークン（Graph API Explorer）と、安定した System User トークン（Business Manager、無期限）です。

トークンがすぐに期限切れになるのはなぜですか？

Graph API Explorer から User access token を取得しているためです。これらは仕様上、約 2 時間で期限切れになります。テスト以外で使う場合は、Business Manager から System User token を生成してください。こちらは無期限です。詳しい手順はこちら。

ads_volume とは何ですか？

Meta は、Facebook ページごとに「配信中または審査中」の広告数を制限しています。デフォルトは 250 件で、この上限はそのページを使用するすべての広告アカウントで共有されます。get_ads_volume ツールを使うと、各ページの残り枠を確認できます。activate_campaigns_batch は事前確認として自動的にこのツールを呼び出します。

無料ですか？

はい。MIT ライセンスで、npm パッケージは無料です。広告費は通常どおり Meta に支払います。この MCP の利用に ScaleForge のアカウントやサブスクリプションは必要ありません。

Pipeboard などの MCP とはどう違いますか？

• Pipeboard／ホスト型 MCP — 提供元のサーバーで稼働し、トークンを提供元に送信します。また、利用頻度も制限されます。ごく少量の利用には適していますが、トークンが他者のマシンに保存されます。
• この MCP — ローカルで稼働するため、トークンが端末の外に出ることはなく、Meta に直接接続します。32 個のツールを備えており、私たちが把握している他のどの Meta MCP よりも幅広く対応しています。
• ScaleForge のマネージドプラットフォーム（下記参照）— マネージド Meta アクセス、RedTrack 連携、スケジュール実行の自動ルール、UI ダッシュボードを必要とするチーム向けの別製品です。この MCP は単独で使えるツールであり、同プラットフォームには依存しません。

ScaleForge なしで使えますか？

はい。この MCP は単独で使える npm パッケージで、graph.facebook.com に直接接続します。アカウントは一切必要ありません。

ツールを追加で提供できますか？

ぜひお願いします。github.com/Mike25app/scaleforge-mcp-meta-ads で PR をお待ちしています。各ツールは src/tools/ 内の小さなファイルです。テンプレートとして既存のファイルを 1 つコピーしてください。

---

ScaleForge の提供

ScaleForge チームが開発・保守しています。マネージド Meta アクセス（System User のプロビジョニング、RedTrack 連携、スケジュール実行の自動ルール、ダッシュボード）が必要な場合は、プラットフォーム全体をご覧ください。この MCP は引き続き無料で、単独で利用できます。

---

セキュリティ

• 最小権限のトークンを生成してください。 システムユーザーのスコープは、必要な広告アカウントとページのみに設定してください。トークンの取り消しは即時に反映されます。
• トークンをソース管理にコミットしないでください。 MCP は META_ACCESS_TOKEN 環境変数から読み取ります。エージェントホストのシークレットストア（Claude Desktop の環境変数ブロック、権限を 600 に設定したシェルプロファイル、1Password など）に保管してください。
• 定期的にローテーションしてください。 有効期限のないシステムユーザートークンも、チームのポリシーに従ってローテーションする必要があります。ビジネスマネージャーで再生成すると、古いトークンは無効になります。
• テレメトリーはありません。 この MCP が外部に通信することはありません。送信リクエスト先は https://graph.facebook.com/v24.0/* のみです。
• レート制限はトークンごと、および広告アカウントごとに適用されます（Meta 側）。一括処理ツールは、制限を超えないよう Meta Batch API を自動的に使用します。

---

リンク

• npm： @getscaleforge/mcp-meta-ads
• GitHub： Mike25app/scaleforge-mcp-meta-ads
• Issue： github.com/Mike25app/scaleforge-mcp-meta-ads/issues
• ScaleForge（マネージドプラットフォーム）： getscaleforge.com
• Meta Marketing API のドキュメント： developers.facebook.com/docs/marketing-apis

---

ライセンス

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