Meta Ads

この動画では、サンプルデータを使ったホスト版 getmcpads を紹介しています。クリエイティブギャラリーやアラートから、Google Sheets へのエクスポートや一括配信まで、MCP Apps はホスト版製品に含まれています。このリポジトリでは、単体で使えるネイティブ API ツールを提供しています。

読み取りツール 42 個 · 書き込みツール 24 個（デフォルトでは無効）

独自のプラットフォーム認証情報と、Claude Desktop、Claude Code、Cursor など stdio MCP に対応するクライアントを使って、ローカルで実行できます。リクエストはプラットフォームに直接送信されます。対応する ChatGPT の構成を含むマネージド接続には、ホスト版をご利用ください。

新着情報

v2.1.1：Zod 4 セキュリティアップデート · 2026 年 10 月 26 日

• zod を 4.6.7 に更新しました。4.6.6 より前のすべての Zod リリースは、重大度の高いアドバイザリ GHSA-mrhx-c7xc-m3w5 の対象です。サイズ制限付きの大きなコレクションを検証するとメモリを使い果たす可能性があり、この修正を含む Zod 3 のリリースはありません。npm audit --omit=dev で脆弱性が再び報告されなくなりました。
• Zod 3 の検証動作を維持します。パラメーターのデフォルト値は使用前に引き続き検証・補完されるため、省略されたオブジェクトにも必須フィールドを指定する必要があります。
• パラメーターが任意、またはデフォルト値を持つ場合でも、各パラメーター固有の説明を維持します。Zod 4 ではラップされたスキーマのみに説明が保存されるため、そうしないと共通のフォールバック説明で置き換えられる可能性があります。
• MCP 経由で公開されるツール名、パラメーター、説明に変更はありません。server-card.json は Zod 4 の JSON Schema 出力で再生成されており、一部の制約の表記が異なります。

以前のリリース

バージョン	日付	主な内容
2.1.0	2026 年 10 月 23 日	ゲートウェイの同期とランタイムのセキュリティアップデート
2.0.1	2026 年 9 月 23 日	公開リポジトリを復元
2.0.0	2026 年 9 月 20 日	ゲートウェイの同期とセキュリティ修正
1.1.0	2026 年 9 月 13 日	プラットフォーム機能の同期と品質要件
1.0.2	2026 年 8 月 30 日	MCP 経由でパッケージのバージョンを通知。
1.0.1	2026 年 8 月 30 日	公式 MCP Registry 向けに、com.getmcpads/meta-ads として server.json と mcpName を追加。
1.0.0	2026 年 8 月 29 日	最初のオープンソースリリース

変更履歴の全文 · すべてのリリース

ソースの同期：SOURCE_SYNC.md。

アップグレードに関する注意

Node.js 22 系では 22.23.4 以降、24 系では 24.22.1 以降、または 26.12.1 以降が必要です。これらのリリースには、2026 年 10 月のセキュリティ修正が含まれています。古いランタイムでもサーバーは起動しますが、stderr に警告が出力されます。CI では Node 22、24、26 を対象にテストしています。meta_health_check は、実行できなかったチェックを「未設定」ではなく「不明」として報告するようになりました。保存済みの引数を再利用する前に、最新のツールスキーマを確認してください。書き込みは引き続きオプションで、明示的な確認が必要です。ホスト型のクリエイティブ連携と MCP Apps UI は、このリリースの対象外です。

このリリースをインストールする

これは GitHub のソースリリースです。npm と MCP Registry のバージョンは別途公開されます。以下のコマンドではこのバージョンを指定します。このドキュメント後半の、バージョンを固定していない npx の例では、npm で現在入手できるバージョンが選択されます。

git clone --branch v2.1.1 --depth 1 https://github.com/get-mcp-ads/meta-ads-mcp-server.git
cd meta-ads-mcp-server
npm ci
npm run build

MCP クライアントが、下記のプラットフォーム認証情報を使用して dist/cli.js の絶対パスを node で実行するように設定してください。

管理された接続をご希望ですか？ ホスト型の getmcpads で Meta Ads を利用する。アカウントを接続し、アシスタントがアクセスできるデータを選択して、ホスト型 MCP 接続を使用します。最新の機能とプランについてはサイトをご覧ください。

利用できる機能

42 個の読み取りツール	キャンペーン、広告セット、広告、クリエイティブ、オーディエンス、ピクセル、カタログ、ページ、Instagram、アクティビティログ、A/B テスト、リフト調査
24 個の書き込みツール	デフォルトでは無効です。ステータス、予算、スケジュール、名前の変更、キャンペーンの作成に対応しています。どの操作も適用前にプレビューを表示します
190 個の指標	クライアント側で算出する派生指標（ROAS、CPA、フリークエンシー、フック率、アトリビューション期間別のビューなど）を含みます
56 個の内訳 · 90 個のディメンション	互換性マトリックスにより、無効な組み合わせを API に送信する前に検出します
7 個のリソース	モデルが読み取れる最新のカタログです。指標、内訳、互換性ルール、11 個のワークフローレシピが含まれます
将来の拡張にも対応した読み取り	meta_get_node_fields、meta_list_edge_raw、meta_get_insights_raw を使うと、このサーバーがまだモデル化していない Graph フィールドにもアクセスできます

クエリプランナー

Meta では、指標と内訳の多くの組み合わせが拒否されますが、エラーメッセージに理由が示されることはほとんどありません。 このサーバーには互換性マトリックスが組み込まれているため、実行できないリクエストを 失敗させるのではなく、複数の有効な API 呼び出しに分割して結果を統合します。

meta_validate_query を使うと、呼び出しを行う前にモデルが組み合わせを確認できます。 これにより、「API がエラー 100 を返しました」と報告するアシスタントと、 実際の数値を返すアシスタントの違いが生まれます。

---

トークンの取得

ここが実際に手間のかかる唯一の手順ですが、適切に設定する価値があります。

ads_read を持つ Meta アクセストークンが必要です。取得方法は 3 つあり、推奨するのは 2 つ目です。

推奨：システムユーザートークン（有効期限なし）

システムユーザーは個人ではなく、ビジネスに紐づきます。そのトークンはパスワードの変更やスタッフの退職の影響を受けず、ビジネスがすでに所有している広告アカウントにアクセスするためのアプリレビューも不要です。

1. ビジネス設定 → ユーザー → システムユーザーに移動します
2. システムユーザーを追加します。追加の権限が必要でなければ、従業員のロールを付与します。
3. アセットを割り当て → 広告アカウントを選択 → パフォーマンスを表示を付与します（書き込みを有効にする場合のみ、キャンペーンを管理も追加します）。
4. 新しいトークンを生成 → アプリを選択 → ads_read スコープを選択します（書き込みを行う場合のみ ads_management を追加します）。
5. 有効期限をなしに設定します。
6. トークンをコピーします。Meta で表示されるのは 1 回だけです。

📖 Meta のシステムユーザーに関するドキュメント

簡単なテスト：Graph API Explorer（有効期限は約 1 時間）

サーバーを試すには適していますが、日常的な作業には向いていません。 Graph API Explorer → アプリを選択 → ads_read を追加 → アクセストークンを生成。

長期間有効なユーザートークン（約60日間）

有効期間の短いトークンを60日間有効なトークンに交換します。2か月ごとに再度行う必要があります。 📖 長期間有効なトークン

必要な権限

権限	必要となる場合
ads_read	常に必要です。 キャンペーン、インサイトなど、読み取り専用のすべての操作
ads_management	META_ENABLE_WRITES=1 を設定する場合のみ
business_management	任意。ビジネスマネージャのアセット検出
pages_show_list, pages_read_engagement	任意。ページ投稿とオーガニックデータの補完
instagram_basic	任意。リンク済みのInstagramアカウント
catalog_management	任意。商品カタログの読み取り

最初の呼び出しとして meta_health_check を実行してください。トークンを表示せずに、実際に付与されているスコープと、使用しようとしたツールに必要なスコープのうち不足しているものを報告します。

---

セットアップ

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS） または %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": ["-y", "@getmcpads/meta-ads-mcp-server"],
      "env": {
        "META_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

Claude Desktopを再起動します。「Metaの広告アカウントを一覧表示して」と尋ねてください。

Claude Code

claude mcp add meta-ads --env META_ACCESS_TOKEN=your-token-here -- npx -y @getmcpads/meta-ads-mcp-server

Cursor

プロジェクト内の .cursor/mcp.json。形式は上記のClaude Desktopの設定と同じです。

ソースから

git clone https://github.com/get-mcp-ads/meta-ads-mcp-server.git
cd meta-ads-mcp-server
npm install && npm run build
cp .env.example .env   # then fill in META_ACCESS_TOKEN
npm start

設定

変数	デフォルト	説明
META_ACCESS_TOKEN	none	必須です。 Metaアクセストークン
META_ENABLE_WRITES	unset	1 に設定すると、24個の書き込みツールを登録します
META_API_VERSION	v26.0	Graph APIのバージョン。別のバージョンに固定するには上書きします
LOG_LEVEL	info	debug、info、warn、error

セットアップはいつでも次の方法で確認できます。

npm run doctor

---

書き込み操作と、事前プレビューを行う理由

書き込みツールはデフォルトで無効です。META_ENABLE_WRITES=1 で有効にします。

有効にすると、すべての書き込みツールはプレビューを返し、変更は行いません。

// meta_update_adset_budget { adSetId: "123", currency: "EUR", dailyBudget: 50 }
{
  "applied": false,
  "action": "meta_update_adset_budget",
  "change": { "adSet": "123", "field": "daily_budget", "amount": 50,
              "currency": "EUR", "inMinorUnits": 5000 },
  "message": "Preview only, nothing was changed. Repeat the same call with confirm: true to apply this change to the live account."
}

実際のアカウントに変更が加えられるのは、confirm: true を指定した2回目の呼び出しだけです。

これは意図的な設計です。アシスタントがこれらの呼び出しを組み立てるため、誤ったアカウントやキャンペーンを選んだり、予算の桁を間違えたりする可能性があります。必須のプレビューによって、費用が発生する前に間違いを確認でき、プロトコルだけでは保証されない、人が操作を止められる機会が設けられます。

さらに、次の2つの安全策があります。

• meta_create_campaign はキャンペーンを必ず PAUSED 状態で作成します。 有効な状態で作成するオプションはありません。
• 予算は通貨ごとの最小単位に換算されます。 円、ウォン、CFAフランには補助通貨単位がないため、12.50円を指定するつもりで1250を送ると、支出額が100倍になります。このサーバーは、小数点以下の桁数が0の通貨を認識します。

ツール	変更内容
meta_update_campaign_status / _adset_status / _ad_status	一時停止または再開
meta_update_campaign_budget / _adset_budget	1日または通算の予算
meta_update_adset_schedule	開始時刻と終了時刻
meta_rename_campaign / _adset / _ad / _ad_account	名前のみ
meta_create_campaign	キャンペーンを作成します。状態は必ず PAUSED です

---

ツール

すべてのツールを以下に記載しています。パラメーターと出力のスキーマ全体については、server-card.json を参照してください。

42個の読み取りツール

| ツール | 目的 | | --- | --- | | `meta_health_check` | 読み取り専用の接続診断です。トークンの識別情報と付与された権限を確認し、アクセストークンを公開することなくアクセス可能な広告アカウントを一覧表示します。 | | `meta_get_business_assets` | アクセス可能なMeta Businessアセット（ビジネス、ページ、Instagramアカウント、ピクセル、データセット）を、権限が許可する範囲で読み取り専用で検出します。 | | `meta_get_pages` | アクセス可能なFacebookページを一覧表示します。利用可能な場合は、ID、名前、カテゴリ、タスク、画像、リンクされたInstagramアカウントの参照情報を含みます。 | | `meta_get_instagram_accounts` | 権限が許可する範囲で、アクセス可能なページ、Business Managerアセット、または広告アカウントにリンクされたInstagramアカウントを一覧表示します。 | | `meta_get_pixels` | アクセス可能な場合に、広告アカウントまたはBusiness Managerのピクセルとデータセットを一覧表示し、権限が制限されているエッジについて対応可能な警告を返します。 | | `meta_get_ad_activity` | `/{ad_account_id}/activities` から広告アカウントのアクティビティログを読み取り、オブジェクト、イベント、実行者、タイムスタンプ、extra_dataの各フィールドを取得します。 | | `meta_get_delivery_diagnostics` | 利用可能な場合はstatus／effective_status／issues_infoと簡易配信インサイトを使用して、キャンペーン、広告セット、広告にわたる読み取り専用の配信診断を集約します。 | | `meta_get_creative_assets` | 広告に関連付けられたクリエイティブメディアを返します。実際の広告名、コレクションのカバー、すべてのカルーセル／フレキシブルコンポーネント、解決済みの画像ハッシュと動画URLを含みます。 | | `meta_get_audience_details` | 権限が許可する範囲で、カスタムオーディエンス、保存済みオーディエンス、類似オーディエンスの詳細を、ページネーションと豊富なフィールド情報とともに読み取ります。 | | `meta_get_catalog_products` | カタログへのアクセスが可能な場合に、商品カタログと商品アイテムを読み取ります。 | | `meta_join_product_insights` | カタログへのアクセスが可能な場合に、商品内訳別のインサイトをクエリし、商品カタログのメタデータで行を補完します。 | | `meta_get_brand_safety_controls` | 広告アカウント／広告セットのターゲティングと、任意のブロックリストエッジから、ブランドセーフティ、適合性、配置、コンテキスト制御に関するシグナルを読み取ります。 | | `meta_interpret_experiment_results` | A/Bテストまたはコンバージョンリフト調査の結果を、信頼性に関するガードレール、セル、目標、任意のセルエンティティとともに読み取り、解釈します。 | | `meta_get_organic_content_enrichment` | Facebookページの投稿とInstagramメディアを、URL、ネイティブ期間、任意のインサイトとともに読み取ります。 | | `meta_list_ad_accounts` | 現在のトークンでアクセス可能なすべてのMeta広告アカウントを一覧表示します。 | | `meta_get_account_details` | 特定のMeta広告アカウントの詳細情報（名前、通貨、タイムゾーン、支出上限、ステータス、ビジネス情報）を取得します。 | | `meta_get_campaigns` | Meta広告アカウントのキャンペーンを一覧表示します。 | | `meta_get_adsets` | Meta広告アカウントの広告セットを一覧表示します。キャンペーンでの絞り込みも可能です。 | | `meta_get_ads` | Meta広告アカウントの広告を一覧表示します。広告セットでの絞り込みも可能です。 | | `meta_get_insights` | Meta広告のパフォーマンスインサイトをクエリします。 | | `meta_get_campaign_structure` | キャンペーン階層（キャンペーン -> 広告セット -> 広告）を取得します。 | | `meta_get_creatives` | 広告クリエイティブのコンテンツ（テキスト、画像、動画、リンク、コールトゥアクション）を取得します。 | | `meta_get_audiences` | Meta広告アカウントのカスタムオーディエンス、保存済みオーディエンス、類似オーディエンスを一覧表示します。 | | `meta_get_ad_studies` | 広告アカウントのコンバージョンリフト調査とA/Bテスト（広告調査）を一覧表示します。 | | `meta_get_study_results` | コンバージョンリフト調査またはA/Bテストの詳細な結果を取得します。 | | `meta_validate_query` | 実行前に、指標と内訳の組み合わせを検証します。 | | `meta_get_page_posts` | 接続ユーザーから解決されたページトークンを使用して、公開済みのFacebookページ投稿を読み取ります。 | | `meta_debug_token` | トークンの識別情報、有効性、有効期限、スコープを確認します。 | | `meta_search_entities` | 広告アカウント内で、名前を指定してキャンペーン、広告セット、または広告を検索します。 | | `meta_get_node_fields` | 1つのMeta Graphノードから任意のフラットフィールドを読み取ります。 | | `meta_list_edge_raw` | 許可リストに含まれる読み取り専用のMeta Graphエッジを、呼び出し元が選択したフラットフィールド、フィルター、カーソルページネーションを指定して一覧表示します。 | | `meta_get_insights_raw` | 検証済みのネイティブフィールド名、内訳、アクション内訳、アトリビューション期間、フィルター、並べ替え、サマリー、ページネーションを使用して、Meta Insightsエッジをクエリします。 | | `meta_search_targeting_options` | Metaの読み取り専用ターゲティングメタデータから、興味関心、検証済みの興味関心、地域、ロケール、国、都市、地域、市場、郵便番号を検索します。 | | `meta_get_ad_preview` | 指定した配置形式で、既存のMeta広告の読み取り専用プレビュー用マークアップを取得します。 | | `meta_list_ad_images` | 広告アカウントの画像ライブラリ（/adimages）を一覧表示します。ハッシュ、名前、寸法、ステータス、常時公開される表示URL（permalink_url）、短期間有効なCDN URL、および各画像を使用するクリエイティブ（任意）を含みます。 | | `meta_list_ad_videos` | 広告アカウントの動画ライブラリ（/advideos）を一覧表示します。タイトル、再生時間、処理ステータス、公開されるサムネイル（推奨サイズと最大サイズ）を含みます。 | | `meta_get_video_sources` | 指定した広告動画の最新のダウンロードURL（source）とサムネイルを解決します。 | | `meta_get_entity_configuration` | 整合性確認のため、広告アカウント内の特定のエンティティを読み取ります。 | | `meta_get_uploaded_video` | 動画の処理状況と、選択したアカウントライブラリへの所属を確認します。 | | `meta_get_adset_configuration` | 編集の準備または広告の追加を行う前に、既存の広告セット、親キャンペーンの予算／目標、アカウントの通貨を読み取ります。 | | `meta_get_promotable_apps` | この広告アカウントで宣伝できるアプリをストアURLとともに一覧表示し、ウェブサイトとアプリ（クロスチャネル）の広告セットを設定できるようにします。 | | `meta_get_catalog_batch_status` | カタログのバッチハンドルについて、完了状況とアイテムごとのエラーを読み取ります。 |

24 個の書き込みツール

デフォルトでは無効です。明示的に確認しない限り、呼び出しはプレビューのみを行います。使用前に設定と正確なスキーマを確認してください。

ツール	目的
meta_create_campaign	広告セット予算（キャンペーン予算は省略）、キャンペーンの日予算、またはキャンペーンの通算予算を指定して、一時停止状態の Meta キャンペーンを作成します。
meta_update_adset_budget	親の予算と既存のスケジュールを確認した後、広告セットの日予算または通算予算を変更します。
meta_update_adset_schedule	明示的なオフセットを含む ISO 8601 形式を使用して、開始時刻や終了時刻を変更します。
meta_update_campaign_budget	通貨と所有権を確認した後、既存のキャンペーン所有予算を変更します。
meta_create_adset	ターゲティング、最適化、配置、アトリビューション、入札、スケジュールを明示して、一時停止状態の Meta 広告セットを作成します。
meta_update_adset_configuration	ターゲティング、最適化、配置、アトリビューション、入札、予算、またはスケジュールを更新します。
meta_duplicate_adset	選択したアカウント内で、正常に動作することが確認済みの広告セットを複製し、複雑なネイティブ設定を維持します。
meta_create_adcreative	既存の投稿、または明示的に指定した object_story_spec と任意の asset_feed_spec から広告クリエイティブを作成します。
meta_create_ad	選択したアカウントの既存の広告セットとクリエイティブを使用して、一時停止状態の広告を作成します。
meta_update_ad_creative	広告のクリエイティブを、同じアカウント内にある別の既存クリエイティブに置き換えます。
meta_upload_ad_image	base64 バイト列を使用して、選択した広告アカウントに画像をアップロードします（デコード後最大 5 MiB）。
meta_upload_ad_video	公開アクセス可能な HTTPS URL、または base64 MP4 バイト列（デコード後最大 5 MiB）から動画をインポートします。
meta_create_custom_audience	ウェブサイト、エンゲージメント、顧客リストのオーディエンス、または類似オーディエンスを作成します。
meta_update_custom_audience	既存のカスタムオーディエンスの名前、説明、保持期間、または完全なルールを更新します。
meta_create_product_set	選択した広告アカウントと同じ Business が所有するカタログに、フィルター済みの商品セットを作成します。
meta_update_product_set	商品セットのフィルターを置き換えるか、名前を変更します。
meta_batch_catalog_items	retailer_id を指定して、最大 50 件のカタログ商品を作成または更新します。
meta_update_campaign_status	Meta キャンペーンを一時停止または再開します。
meta_update_adset_status	Meta 広告セットを一時停止または再開します。
meta_update_ad_status	Meta 広告を一時停止または再開します。
meta_rename_campaign	Meta キャンペーンの名前を変更します。
meta_rename_adset	Meta 広告セットの名前を変更します。
meta_rename_ad	Meta 広告の名前を変更します。
meta_rename_ad_account	Meta 広告アカウントの名前を変更します。

7 個のリソース

URI	内容
meta://manifest	このサーバーが公開する内容と、最初に実行するツール
meta://metrics	カテゴリと形式を含む、全 190 件の指標
meta://breakdowns	全 56 件のブレークダウンと、それぞれが有効な場所
meta://compatibility	90 個のディメンションを含む互換性マトリックス
meta://recipes	11 件の手順ごとのワークフロー
meta://p2-readonly	読み取り専用スコープに関するガイダンス
meta://app-review	Meta App Review の申請におけるスコープの位置付け

---

セキュリティ

このサーバーは、広告アカウントのライブデータを読み取り、書き込みが有効な場合は変更できる認証情報を保持します。 具体的には、次のとおりです。

• トークンは、どのログレベルでも記録されず、ディスクにも書き込まれません。
• リクエストの送信先は、固定バージョンの graph.facebook.com のみです。 それ以外のホストは呼び出されず、拒否されます。テストで確認済みです。
• トークンを付与した後のリダイレクトは拒否されるため、リダイレクトによって認証情報が別の場所に転送されることはありません。 テストで確認済みです。
• テレメトリーはありません。 サーバーが行うネットワーク通信は Graph API 宛てのみです。分析、ホームへの通信、使用状況の報告はありません。ソース内で fetch を検索すれば確認できます。

ポリシーの全文と報告手順：SECURITY.md。

---

マネージド型のマルチプラットフォーム版をお探しですか？

ローカルサーバーを運用せずにこのソースを使いたい場合は、ホスト型 Meta Adsをお試しください。 getmcpads は、広告、Search Console、GA4 も 1 つの MCP URL で接続できます。 利用可能なソースとプランの制限はサイトに記載されています。アカウントの接続は引き続き必要です。

1. Meta Ads 接続ガイドに従ってください。
2. アシスタントによる読み取りを許可するアカウントまたはプロパティを選択してください。
3. Claude、 ChatGPT、または Codexを接続してください。
4. 読み取り専用のレビューをお試しください：「キャンペーンの結果を比較し、CTR とあわせてフリークエンシーを調査してください。不足しているデータを明示し、何も変更しないでください。」

有料プランを選ぶ前に、現在のホスト型ツールカタログと 料金をご確認ください。 この Apache 2.0 アダプターは、ご自身の認証情報を使って引き続き単独でご利用いただけます。

---

コントリビューション

Issue とプルリクエストを歓迎します。CONTRIBUTING.mdをご覧ください。 セキュリティ関連の報告を行う前に、SECURITY.mdをお読みください。

ライセンス

Apache License 2.0。NOTICEもご覧ください。

Facebook、Meta、Instagram、および Meta Marketing API は、Meta Platforms, Inc. の商標です。 このプロジェクトは Meta Platforms, Inc. と提携、承認、または後援関係にありません。 公開 API を利用する独立したクライアントです。

MCP コントラクトとデスクトップバンドル

すべてのツールで、読み取り／書き込みのアノテーション、パラメーターの説明、構造化出力スキーマを宣言しています。呼び出しが成功すると、ペイロードは structuredContent.result として公開されます。エラーの場合は isError: true が保持されます。生成されたサーバーカードには定義のみが含まれます。

npm run bundle -- /path/to/outputを実行すると、現在のカタログから.mcpbデスクトップバンドルをビルドできます。認証情報はインストール時にローカルで入力します。書き込みツールは、明示的に有効にしない限り無効のままです。

getmcpads のその他のサービス

Google Ads · Google Analytics 4 · Google Search Console · TikTok Ads · Pinterest Ads · X Ads

getmcpadsのEmmanuelがメンテナンスしています。お問い合わせ：[email protected]。