Meta MCP Connector

Meta / Facebook Ads を Graph API 経由で操作するための、平易な言葉で使える MCP サーバーです。

広告アカウント、キャンペーン、広告セット、支出、パフォーマンスについて自然言語で質問できます。テーブル名や生の API パスは不要です。

特徴

• Facebook Marketing API (Graph API) からのライブデータ

• 親の Business Manager を含む広告アカウントの一覧

• キャンペーン / 広告セット / 広告のパフォーマンス（支出、インプレッション、クリック、購入）

• アカウントレベルの支出ダッシュボード (account-spend.html)

• Cloud Run にデプロイした場合の Claude.ai OAuth (MCP_PUBLIC_URL)

Related MCP server: Instagram Ads MCP Server

プロジェクト構成

meta-mcp-connector/
├── meta_mcp_server.py    # MCP server + HTTP routes + tools
├── meta_graph.py         # Facebook Graph API client
├── meta_oauth.py         # Claude-compatible OAuth provider
├── account-spend.html    # Spend-by-account dashboard
├── test-accounts.html    # Ad account list test page
├── get-token.html        # Helper to obtain FACEBOOK_ACCESS_TOKEN
├── requirements.txt
├── Dockerfile
├── deploy-cloudrun.ps1   # Deploy to Google Cloud Run
├── .env.example
└── .cursor/mcp.json      # Local Cursor MCP config (example)

セットアップ（ローカル）

1. クローンとインストール

git clone https://github.com/YOUR_USERNAME/meta-mcp-connector.git
cd meta-mcp-connector
python -m venv .venv

# Windows
.venv\Scripts\activate

pip install -r requirements.txt
copy .env.example .env

2. .env の設定

FACEBOOK_APP_ID=your_app_id
FACEBOOK_APP_SECRET=your_app_secret
FACEBOOK_ACCESS_TOKEN=your_user_token_with_ads_read
FACEBOOK_AD_ACCOUNT_ID=114810198697538

トークンの要件

• ユーザートークン (EAA…) である必要があります。アプリトークン (app_id|secret) は不可

• Graph API Explorer で あなたの FACEBOOK_APP_ID 用に生成

• 権限: ads_read, ads_management, business_management

get-token.html を使用するか、サーバーを起動して http://127.0.0.1:8001/get-token を開いてください。

3. サーバーの起動

python meta_mcp_server.py --http

4. Cursor MCP 設定

.cursor/mcp.json:

{
  "mcpServers": {
    "meta": {
      "url": "http://127.0.0.1:8001/mcp"
    }
  }
}

サーバー起動後、Cursor の設定で MCP をリロードしてください。

MCP ツール

プロンプト例

• "Meta の広告アカウントを一覧表示"

• "2026-08-01 から 2026-08-15 までの Meta 広告サマリー"

• "WOW Ad Account の過去 7 日間の日別支出"

• "昨日の支出上位の広告"

• "先週のキャンペーン別支出の内訳"

Google Cloud Run

同じ HTTP MCP エンドポイントを Cloud Run でホストします（vdp-connector と同じパターン）。Docker イメージには .env やシークレットは焼き込まれません。

前提条件

• Google Cloud SDK (gcloud) がインストールされ、ログイン済み (gcloud auth login)

• 課金が有効な GCP プロジェクト

• GCP の プロジェクト ID

• Facebook の認証情報がローカルの .env にある（.env.example 参照）

デプロイ

このリポジトリのフォルダから:

# App secret read from .env
.\deploy-cloudrun.ps1 -ProjectId "YOUR_GCP_PROJECT_ID"

# Optional overrides
.\deploy-cloudrun.ps1 -ProjectId "YOUR_GCP_PROJECT_ID" -Region "us-central1" -Service "meta-mcp"

# App secret from a one-line file (gitignored)
.\deploy-cloudrun.ps1 -ProjectId "YOUR_GCP_PROJECT_ID" -SecretFile ".\facebook-app-secret.key"

スクリプトの処理内容:

1. Cloud Run、Cloud Build、Secret Manager、Artifact Registry を有効化

2. FACEBOOK_APP_SECRET を Secret Manager にアップロード (meta-facebook-app-secret)

3. .env に設定されている場合、FACEBOOK_ACCESS_TOKEN を Secret Manager にアップロード (meta-facebook-access-token)

4. --source . (Dockerfile) でデプロイし、環境変数とシークレット注入を設定

5. MCP_PUBLIC_URL をサービス URL に設定（Claude OAuth に必要）

6. コネクタ URL を出力: https://SERVICE-URL/mcp

デプロイフラグ:

• --set-env-vars MCP_TRANSPORT=http,HOST=0.0.0.0,FACEBOOK_APP_ID=…,FACEBOOK_AD_ACCOUNT_ID=…

• --set-secrets FACEBOOK_APP_SECRET=meta-facebook-app-secret:latest,FACEBOOK_ACCESS_TOKEN=meta-facebook-access-token:latest

• --allow-unauthenticated (初回デプロイで MCP URL を機能させるために必要)

• --session-affinity, --max-instances 1, --timeout 300, --port 8080

Cursor (Cloud Run)

デプロイ後、出力された URL を .cursor/mcp.json に記入:

"meta": {
  "url": "https://YOUR-CLOUD-RUN-URL/mcp"
}

Cloud Run を使用する場合、ローカルで python meta_mcp_server.py を実行する必要はありません。

Claude カスタムコネクタ

Claude.ai はリモートのカスタムコネクタに OAuth を必須 としています。このサーバーは、MCP_PUBLIC_URL が設定されている場合（デプロイスクリプトが自動設定）、Claude 互換の OAuth プロバイダー（Dynamic Client Registration）を内蔵しています。

1. .\deploy-cloudrun.ps1 -ProjectId "YOUR_GCP_PROJECT_ID" でデプロイ

2. 古い壊れたコネクタを削除

3. 設定 → コネクタ → カスタムコネクタを追加

4. 正確に貼り付け: https://YOUR-CLOUD-RUN-URL/mcp (/mcp を含める必要あり)

5. 詳細設定の OAuth Client ID は空のまま（DCR が有効）

6. 接続をクリック — Claude が自己登録し、短時間の認証が行われます

"サインインサービスに登録できませんでした" (ofid_…) が表示される場合:

• URL が /mcp で終わっていることを確認（ベアの Cloud Run ホストではない）

• サービスが稼働していることを確認: https://YOUR-CLOUD-RUN-URL/.well-known/oauth-authorization-server を開き、registration_endpoint を含む JSON が表示されることを確認

• MCP_PUBLIC_URL がサービスオリジンと一致していることを確認（URL を変更した場合は再デプロイ）

• 外部 IdP を設定していない限り、ランダムな OAuth Client ID を貼り付けない

デプロイの確認

ローカル vs クラウド

セキュリティに関する注意

--allow-unauthenticated により、Cloud Run の URL は公開アクセス可能になります。OAuth により、Claude はツールが動作する前に登録/認証を完了する必要があります。トークンを持たないランダムな呼び出し元は 401 を受け取ります。それでも URL は機密情報として扱い、広く共有する前に強力な認証を追加してください。

よくある落とし穴

1. Claude の URL に /mcp がない → "サーバーに接続できません"

2. MCP_PUBLIC_URL が未設定 → OAuth 404 → "サインインサービスに登録できません"

3. .env やシークレットファイルをコミットしてしまう

4. OAuth コード変更後に再デプロイを忘れる

5. FACEBOOK_ACCESS_TOKEN なしでデプロイ → Graph API が権限エラーを返す

GitHub へのプッシュ

# Sign in to your new GitHub account first
git credential-manager github login --force

# Create repo on GitHub (browser or gh), then:
git remote add origin https://github.com/YOUR_USERNAME/meta-mcp-connector.git
git add .
git commit -m "Initial commit: Meta MCP connector"
git push -u origin main

セキュリティ

• .env をコミットしない — gitignore されています

• FACEBOOK_ACCESS_TOKEN はシークレットです。漏洩した場合はローテーションしてください

• Cloud Run デプロイでは MCP URL の到達性のために --allow-unauthenticated を使用します。MCP_PUBLIC_URL が設定されている場合、OAuth がツールアクセスを保護します