Meta Ads MCP Server

AIと会話するだけで、Meta広告（Facebook / Instagram）を管理・分析できるMCPサーバー

普段Meta広告マネージャーでやっている操作 ― レポートの確認、キャンペーン作成、ターゲティング変更、予算調整、クリエイティブ管理まで ― を、AIとのチャットだけで完結できます。広告マネージャーを開く必要はありません。

---

特徴

• 30のツール — 読み取り18 + 書き込み12で、Meta広告の管理を網羅
• 安全設計 — 書き込み操作はデフォルトで dry_run（プレビューのみ）。新規作成はすべて PAUSED 状態
• OAuth対応 — ブラウザでFacebookログインするだけで認証完了。トークンは約60日間有効
• Claude Desktop / Claude Code / Cursor 対応 — MCP互換のAIクライアントならどれでも使用可能
• 依存最小 — Python + requests + python-dotenv のみ。追加SDKは不要

---

クイックスタート

1. リポジトリをクローン

git clone https://github.com/nishi0077/meta-ads-mcp.git
cd meta-ads-mcp

2. 依存パッケージをインストール

python -m venv .venv

# Mac/Linux:
source .venv/bin/activate
# Windows:
.venv\Scripts\activate

pip install -r requirements.txt

3. 環境変数を設定

cp .env.example .env

.env を編集して Meta App の情報を入力します（Meta App の作成方法はこちら）。

META_AUTH_TYPE=oauth
META_APP_ID=あなたのアプリID
META_APP_SECRET=あなたのApp Secret
META_AD_ACCOUNT_ID=act_xxxxxxxxxxxxx   # 任意。空でもOK
META_API_VERSION=v24.0

4. 初回認証

python meta_ads_server.py

ブラウザが開き、Facebookログイン画面が表示されます。ログインして「許可」するとトークンが保存されます（約60日間有効）。

5. AIクライアントに接続

Claude Desktop

設定ファイル（Mac: ~/Library/Application Support/Claude/claude_desktop_config.json / Windows: %APPDATA%\Claude\claude_desktop_config.json）に追加：

{
  "mcpServers": {
    "meta-ads": {
      "command": "/path/to/meta-ads-mcp/.venv/bin/python",
      "args": ["/path/to/meta-ads-mcp/meta_ads_server.py"]
    }
  }
}

Windows の場合、command は .venv\\Scripts\\python.exe に変更してください。

Claude Code

claude mcp add meta-ads -- python /path/to/meta-ads-mcp/meta_ads_server.py

Cursor

Cursorの設定 → MCP → 「Add new MCP server」で以下を設定：

• Name: meta-ads
• Type: command
• Command: python /path/to/meta-ads-mcp/meta_ads_server.py

---

使い方

接続したら、AIに話しかけるだけで使えます。

「アカウント一覧を見せて」

「過去30日間のキャンペーン成果を教えて」

「広告を年齢×性別でブレイクダウンして」

「キャンペーンの日予算を5,000円に変更して」

「このキャンペーンを一時停止して」

「25-45歳女性、日本向けの広告セットを作って」

「この画像をアップロードして、クリエイティブを作って」

「成果の悪い広告を停止して」

「2つの広告クリエイティブを比較分析して」

「全アカウントの今月の広告費を一覧して」

---

ツール一覧

読み取り系（18ツール）

ツール	説明
list_ad_accounts	アクセス可能な広告アカウント一覧
get_account_info	アカウント詳細（通貨・タイムゾーン・残高）
list_campaigns	キャンペーン一覧（ステータス・予算・目的）
get_campaign_performance	キャンペーン成果（クリック・費用・CPC・CTR等）
list_adsets	広告セット一覧（ターゲティング・予算）
get_adset_performance	広告セットごとの成果比較
list_ads	広告一覧（クリエイティブ情報付き）
get_ad_performance	広告別の成果比較
get_insights	カスタムレポート（年齢・性別・配置面等でブレイクダウン）
get_ad_creatives	広告クリエイティブ（画像・テキスト・CTA）
get_ad_previews	広告プレビュー（HTML形式）
get_image_assets	画像アセット一覧
get_video_assets	動画アセット一覧
get_custom_audiences	カスタムオーディエンス一覧
list_pages	Facebookページ一覧
list_instagram_accounts	Instagramアカウント一覧
download_ad_images	広告画像をローカルにダウンロード
analyze_ad_creative	クリエイティブの詳細分析（A/B比較向け）

書き込み系（12ツール）

ツール	説明
create_campaign	キャンペーン作成（PAUSED）
update_campaign	キャンペーン名・予算の更新
pause_enable_campaign	キャンペーンの一時停止・再開
update_campaign_budget	キャンペーン予算の変更
create_adset	広告セット作成（ターゲティング・予算設定）
update_adset	広告セットの更新
pause_enable_adset	広告セットの一時停止・再開
create_ad	広告作成（PAUSED）
update_ad_status	広告の一時停止・再開
create_ad_creative	クリエイティブ作成（画像・動画）
upload_image	画像アップロード（URL or ローカル）
create_custom_audience	カスタムオーディエンス作成

安全設計

• 書き込み系はすべて dry_run=true（プレビュー）がデフォルト
• 「こう変わります」を確認してから dry_run=false で実行
• 新規作成はすべて PAUSED（停止）状態 で作成 — うっかり配信される心配なし

---

Meta App の作成

初回のみの作業です。5分程度で完了します。

1. App の作成

1. Meta for Developers にアクセスしてログイン
2. 「マイアプリ」→「アプリを作成」
3. 設定：
   • ユースケース: 「その他」→「次へ」
   • アプリタイプ: 「ビジネス」→「次へ」
   • アプリ名: 好きな名前（例: My Meta Ads MCP）
   • ビジネスアカウント: 自分のMeta Businessアカウントを選択
4. 「アプリを作成」

2. Marketing API の追加

1. アプリダッシュボードで「プロダクトを追加」
2. Marketing API を見つけて「設定」

3. App ID と App Secret の取得

1. 左メニュー「アプリ設定」→「ベーシック」
2. アプリID と App Secret をコピー

App Secret は絶対に他人に共有しないでください。

4. ビジネス認証（広告の作成・編集に必要）

読み取り専用（レポート確認等）はビジネス認証なしでも使えます。広告の作成・編集には認証が必要です。

1. Meta Business Settings →「セキュリティセンター」
2. 「ビジネス認証を開始」→ 書類をアップロード（通常 2〜7 営業日）

---

認証方式

方式	設定	おすすめ
OAuth（デフォルト）	META_AUTH_TYPE=oauth + App ID/Secret	個人・小規模運用
System User Token	META_AUTH_TYPE=system_user + META_ACCESS_TOKEN	大規模・自動化

---

トラブルシューティング

症状	対処法
Python が見つからない	python --version で確認。3.11以上が必要
接続エラー	.env の設定を確認。AIクライアントを再起動
トークン期限切れ	meta_ads_token.json を削除して python meta_ads_server.py で再認証
権限エラー	Meta App に ads_read, ads_management 権限があるか確認
レート制限	しばらく待って再実行。Meta API はスコアベースのレート制限
APIバージョンエラー	.env の META_API_VERSION を最新に変更

---

技術情報

• プロトコル: Model Context Protocol (MCP)
• API: Meta Graph API（直接リクエスト、SDK不使用）
• 認証: OAuth 2.0 + ローカルHTTPコールバック / System User Token
• APIバージョン: v24.0（.env で変更可能）

---

ライセンス

MIT License