facebook-mcp

facebook-mcp — Facebookページ MCP サーバー

📖 ドキュメントサイト →

Meta Graph API 向けの、ローカルファーストな TypeScript 製Model Context Protocol （MCP）サーバーです。Facebookページに特化し、MCP クライアント（Claude、VS Code、Inspector など）から操作できるほか、Page 管理者が自身の Meta 開発者アプリを使ってローカルで運用できます。投稿の公開、閲覧とインサイトの確認、コメントやメッセージのモデレーションに対応します。最小権限のトークン、計画してから適用する書き込みの安全対策を備え、テレメトリーはありません。

🚧 ステータス：1.0 未満で、現在も開発中です。 npm で @ivanbaev/facebook-mcp として公開されています。バージョン番号がその警告です。

7 つすべてのツールパッケージが実装済みです。正確な機能範囲については ツール一覧をご覧ください。実際の Graph API に対する検証はまだ一切行われていません。 このリポジトリのすべてのテストは、実際の fetch を実行すると例外をスローする ネットワーク遮断環境下で、フェイクと記録済みのフィクスチャを使って実行されます。そのため、「テストが成功する」とは「コードがフィクスチャの指示どおりに動作する」という意味であり、「Meta が受け入れた」という意味ではありません。ライブスモークテスト用ハーネス (scripts/smoke/)はありますが、リリース済みのどの状態でも実際の Page に対して実行されていません。以下の機能はすべて実装済みですが、実証されていないものとして扱い、1.0 までは破壊的変更があることを想定してください。また、何かに依存する前に 既知の制限事項をお読みください。

目次： 機能 · 要件 · セットアップ · クライアントの互換性 · 認証情報の設定 · 権限 · ツール · 比較 · 既知の制限事項 · 対象外 · 運用者の責任 · ロードマップ · セキュリティに関する注意事項 · ドキュメント · サポート · 商標 · ライセンス

機能

実装状況のみを示しています。「実装済み」の意味と、意味しない内容については、上記のステータスに関する注記をご覧ください。

領域	機能	ステータス
コアと診断	ID、ページ一覧、レート制限の使用状況、doctor による事前チェック	✅ 実装済み、実環境での検証なし
読み取り	ページと投稿の読み取り、リール、リアクション、カーソルページネーション	✅ 実装済み、実環境での検証なし
公開	テキスト／リンク／写真／動画／リールの投稿、予約投稿、編集と削除	✅ 実装済み、実環境での検証なし
インサイト	ページと投稿のインサイト、フラットな行形式と指標ごとの概要、非推奨化への対応	✅ 実装済み、実環境での検証なし
モデレーション	コメントの読み取り、返信、非表示／削除、非公開での返信、ブロック／ブロック解除	✅ 実装済み、実環境での検証なし
メッセージング	24 時間のウィンドウ内での会話の読み取りと返信	✅ 実装済み、実環境での検証なし
広告	キャンペーン／広告セット／広告の読み取り、インサイト、ステータスと予算の管理 — デフォルトでは無効	✅ 実装済み、実環境での検証なし
実環境での検証	実際のページと広告アカウントに対して、すべてのツールを実行	❌ 未実施 — ステータスに関する注記をご覧ください
npm／MCPB のリリース	npx @ivanbaev/facebook-mcp、検証済みバンドル、レジストリへの掲載	✅ 公開済み — 0.7.0

デフォルトのプロファイルでは、意図的に小規模で厳選されたツール群を公開します。各 ツールは Graph のすべてのエッジをそのまま反映するのではなく、実際の機能を 1 つずつラップします。

• ローカル優先、テレメトリーなし。 アクセスするのは 3 つの Meta ホストのみです （graph、graph-video、rupload）。外部への情報送信はありません。
• 最小権限の認証情報。 有効期限のないシステムユーザートークン （Business Manager）または長期有効なページトークンで動作します。管理者が自身のアセットを操作する場合、アプリレビューは不要です。
• 安全な書き込み。 段階的な計画・適用ゲートを備えています。取り消せない操作や支出を伴う操作には、帯域外での確認が必要であり、環境変数フラグで回避することはできません。
• シークレットの衛生管理。 ログ、エラー、ツールの結果、書き込みジャーナルに対して、単一の要所で値に基づく秘匿化を行います。
• 階層化アーキテクチャ。 Lint で強制される core ← api ← mcp ← tools の階層と、中央パッケージレジストリを用いたデータとしてのツールを採用しています。

要件

• Node.js ≥ 22（engines とランチャーの実行時ガードで強制されます。 プロジェクトは .nvmrc で指定されたバージョンを対象とします）。
• Meta（Facebook）の開発者アプリ — Standard Access の Business タイプのアプリで 十分です。自身のアセットを操作する場合、アプリレビューは不要です。
• 管理者権限を持つ Facebook ページ（および、オプトインの ads パッケージを使用する場合は、広告アカウント）。

セットアップ

初回の実行は、次の順に5つの手順で行います。所要時間は約20分です。その大半はMetaのアプリのUIでの操作です。トラブルシューティングを含む詳細版はdocs/runbooks/onboarding.mdをご覧ください。

1. Metaアプリ — https://developers.facebook.com/appsでBusinessタイプのアプリを作成し、App IDとApp Secret（Settings → Basic）を控えます。setup-tokenには両方が必要です。

2. 短期間有効なトークン — Graph API Explorerでアプリを選び、User Tokenを選択して、必要なスコープ（少なくともpages_show_listとpages_read_engagement）にチェックを入れ、Generate Access Tokenをクリックします。有効期間は1～2時間なので、すぐに手順3を行ってください。

3. トークンを交換して環境ファイルを書き込む — setup-tokenでトークンを約60日間有効なトークンと交換し、ページを特定して環境ファイルを書き込みます。

   FB_APP_ID='<app id>' FB_APP_SECRET='<app secret>' \
   FB_SETUP_TOKEN='<explorer token>' \
     npx -y @ivanbaev/facebook-mcp setup-token
   

   Runブロックのstatus: completedと、Env fileブロックのstatus: writtenが成功を示します。ファイルは~/.config/facebook-mcp/.env（設定されている場合は$XDG_CONFIG_HOME）またはWindowsでは%APPDATA%\facebook-mcp\.envに、モード0600で保存されます。サーバーは起動のたびにこのファイルを読み込むため、以下のクライアント設定にenvブロックは不要です。ページが複数ある場合は、--page=<id> --forceを付けて再実行してください。

4. 事前確認 — 使用する予定の各パッケージがusableであることを確認します。

   npx -y @ivanbaev/facebook-mcp doctor
   

5. サーバーをクライアントに登録して、最初の呼び出しを行う — 次の2つのサブセクションを参照してから、クライアントに「facebook_whoamiを実行して」と依頼します。トークンの種類とページ名を示す応答が、最初のツール呼び出しの成功を意味します。

doctorとsetup-tokenのレポートには、起動時に使用した形式でコマンドが記載されます（npx -y @ivanbaev/facebook-mcp …、グローバルインストール後はfacebook-mcp …、またはソースをチェックアウトした場所からはnode build/index.js …）。--helpの出力にはfacebook-mcp …と記載されるため、起動時に使用した形式に置き換えてください。どのサブコマンドも、ネットワークに接続せずに--helpを実行できます。

(a) npxを使用する場合

Claude Code — コマンドを1つ実行し、セッション内で/mcpを確認します。

claude mcp add facebook -- npx -y @ivanbaev/facebook-mcp

デフォルトでは現在のプロジェクトディレクトリに登録されます。どこからでも使えるようにするには、--scope userを追加してください。同じコマンドを設定するプラグインとしてインストールすることもできます。

/plugin marketplace add IvanBBaev/facebook-mcp
/plugin install facebook-mcp

Claude Desktop — Settings → Developer → Edit Configを開くと、claude_desktop_config.jsonが開きます（macOS： ~/Library/Application Support/Claude/、Windows：%APPDATA%\Claude\）。サーバーを追加して保存し、Claude Desktopを終了して再起動してください。

{
  "mcpServers": {
    "facebook": {
      "command": "npx",
      "args": ["-y", "@ivanbaev/facebook-mcp"]
    }
  }
}

Claude Desktopはシェルのプロファイルを読み込みません。Nodeをバージョン管理ツール（nvm、fnm、asdf）経由で使用していて、サーバーが起動しない場合は、npxの絶対パス（which npx）をcommandに指定してください。

その他のstdioクライアントでも、同じcommand／argsの組み合わせを使用します。クライアントの互換性をご覧ください。

Claude Desktopバンドル（別の方法） — 最新リリースに添付されている.mcpbは、ダブルクリックでインストールできます。設定フォームではすべての認証情報が任意項目として表示されます。空欄にすると、手順3で作成した環境ファイルが使われます（空欄の値が環境ファイルの内容を上書きすることはありません）。このバンドルにはビルド元を証明するアテステーションが付属しているため、インストール前に、このリポジトリのワークフローから作成されたことを検証できます。

gh attestation verify facebook-mcp-0.7.0.mcpb --repo IvanBBaev/facebook-mcp

(b) ソースから実行する場合

開発用、またはまだリリースされていないコミットを実行する場合：

git clone https://github.com/IvanBBaev/facebook-mcp.git
cd facebook-mcp
npm install
npm run build
node build/index.js setup-token   # with the same FB_* variables as step 3
node build/index.js doctor        # pre-flight: token, scopes, package matrix
node build/index.js               # or: ./bin/facebook-mcp.mjs

MCPクライアントで、このコマンドを絶対パスで指定します。envブロックは任意です。指定しない場合、サーバーは環境ファイルを読み込みます。ここに空欄でない値を指定すると、環境ファイルの値より優先されます。

{
  "mcpServers": {
    "facebook": {
      "command": "node",
      "args": ["/absolute/path/to/facebook-mcp/build/index.js"],
      "env": { "FB_SYSTEM_TOKEN": "…", "FB_PAGE_ID": "…" }
    }
  }
}

クライアントとの互換性

これはクライアント固有のコードを含まない標準的な stdio MCP サーバーのため、プロトコルに対応する環境であればどこでも動作するはずです。「はず」という点が重要です。 この表には、各クライアントに必要な設定と、その方法が実際に試されたかどうかを記載しています。動作を保証するものではありません。

クライアント	登録方法	確認済み？
Claude Desktop	claude_desktop_config.json → mcpServers、または .mcpb バンドル	❌ 未確認 — バンドルはエンドツーエンドでインストールされていません
Claude Code	claude mcp add、またはこのリポジトリのプラグインマーケットプレイス	❌ 未確認
VS Code (Copilot Chat / agent)	.vscode/mcp.json → servers	❌ 未確認
Cursor	~/.cursor/mcp.json → mcpServers	❌ 未確認
Windsurf、Zed、Cline、…	stdio JSON-RPC に対応する任意のクライアント	❌ 未確認
MCP Inspector	node build/index.js を指定	❌ 未確認

自動テストで確認済みの内容は次のとおりです。

• stdio のフレーミング — テストでは、ビルド済みサーバーを実際のサブプロセスとして起動し、パイプ経由で initialize → tools/list → tools/call のハンドシェイク全体を実行して、標準出力にはプロトコルフレームのみが出力されること（すべてのログは標準エラー出力に送られること）を検証します。
• ツールのコントラクト — すべてのツールの入力／出力スキーマ、アノテーション、書き込みティア、エラーマッピングを、フェイクと記録済みフィクスチャに対してユニットテストしています。
• HTTP トランスポート — ループバックバインディング、ベアラートークンの拒否、セッション処理を、実際のローカルサーバーに対して検証しています。

これらはいずれも MCP クライアントや Meta API を利用していません。クライアントで動作させることができたら、issue でお知らせください — そうすることで、この表に ✅ が増えていきます。

プラットフォームに関する注意事項

CI では Linux（Node 22/24/26）と Windows（Node 22）で全チェックを実行しています。主な開発環境は macOS ですが、CI には含まれていません。環境ファイル、書き込みジャーナル、FB_MEDIA_DIR のパスは、POSIX では XDG、Windows では %APPDATA% に従います。

認証情報を設定する

facebook-mcp はすでにあなたが管理しているトークンで認証します — App Review、OAuth コールバックサーバー、ホストされたコンポーネントは不要です。以下のトークン変数から少なくとも1つを指定してください。最も具体的なものが優先されます（FB_SYSTEM_TOKEN → FB_ACCESS_TOKEN → FB_PAGE_TOKEN）。

• FB_SYSTEM_TOKEN — 有効期限のないシステムユーザートークン（Business Manager）。推奨：有効期限がなく、割り当てたアセットだけに権限が限定されます。
• FB_ACCESS_TOKEN — Meta ユーザーアクセストークン（長期有効のものを推奨）。
• FB_PAGE_TOKEN — 長期有効のページトークン。Business Manager を使わない場合の代替手段です。特定の1つのページにのみ属するため、あわせて FB_PAGE_ID にそのページを設定してください（doctor / facebook_whoami で操作対象のページとして報告されます）。

有効にするパッケージが実際に必要とする権限だけを付与し（必要な権限の一覧はこちら）、FB_APP_SECRET を設定して、すべての呼び出しに appsecret_proof が付与されるようにしてください。これにより、盗まれたトークン単体では利用できなくなります。設定は、XDG／%APPDATA% の設定パスにある環境ファイル、または実際の環境変数から読み込まれます（環境変数が優先されます）。 環境ファイルを手作業で作成したくない場合は、 npx -y @ivanbaev/facebook-mcp setup-token（ソースから実行する場合は node build/index.js setup-token）を実行してください。ガイド付きフローでトークンを交換・分類し、環境ファイルを作成します（上書きするには --page=<id>、--env-file=<path>、--force、動作を試すには --no-write／--dry-run を指定します。トークンはコマンドラインではなく FB_SETUP_TOKEN で渡してください。交換には FB_APP_ID と FB_APP_SECRET も必要です）。詳しい手順については、docs/runbooks/onboarding.md を参照してください。

その後、ほかの作業に進む前に doctor（npx -y @ivanbaev/facebook-mcp doctor）を実行してください。トークンを検査し、種類、有効期限、付与されたスコープを報告します。また、パッケージごとの利用可能／一部利用可能／ブロックの一覧を表示するため、ツールを呼び出す前に不足している権限を確認できます。最後に、検出されたすべての項目について、1 行の判定を表示します。

doctor はレポートを出力するだけなので、検出内容にかかわらず終了コード 0 で終了します。その出力をテキストとして処理するラッパーも引き続き動作します。--strict を追加すると、代わりにゲートとして動作します。

判定	--strict 指定時	意味
OK	終了コード 0	対処が必要な項目はありません。
WARN	終了コード 1	サーバーは動作しますが、何らかの機能が低下しています（スコープの不足、まもなく有効期限を迎えるトークン、全ユーザーが読み取り可能な環境ファイル、Graph が受け付けなくなった指標名など）。
UNKNOWN	終了コード 1	チェックを完了できませんでした。通常は debug_token に到達できず、認証情報が不正なのではなく未検証の状態です。
FAIL	終了コード 2	この設定ではリクエストを処理できません。トークンがない、Graph が拒否するトークン、アセットへのアクセスが取り消されている、または利用可能なパッケージがない状態です。

UNKNOWN は意図的に WARN より優先されます。「何も確認できていない」状態が「機能が低下している」状態に隠れてはいけません。POSIX の権限ビットに対応していないプラットフォームでは、認証情報ファイルについて問題は報告されません。そこでは推奨できる chmod がなく、解消できない警告があると、Windows では --strict が常に失敗するためです。

node build/index.js --version（または -v）を実行すると、サーバー、Node、MCP SDK のバージョンが 1 行で出力され、終了します。認証情報は不要なため、起動できないインストール環境でもバージョンを確認できます。

facebook-mcp 0.7.0 (node v22.23.0, darwin arm64, sdk 1.30.0)

サーバーのバージョンは常に 2 番目のフィールドにあるため、--version | awk '{print $2}' も引き続き動作します。同じ 3 つのバージョンに加え、固定された Graph API のバージョンは、facebook_whoami の server オブジェクト（name、version、apiVersion、sdkVersion）でも報告されます。--help（または -h）を実行すると、コマンドの概要と初回実行時の手順が標準出力に表示され、終了コード 0 で終了します。この場合も認証情報は読み込まれません。setup-token --help と doctor --help も同様に、処理を実行せずヘルプを表示します。単独で終了する引数は doctor、setup-token、--version、--help のみです。それ以外の引数では stdio サーバーが起動し、JSON-RPC を待ち受けます。doctor が認識しない引数（たとえば --stric）ではゲート処理は行われませんが、レポートにはその引数が記載されます。値ではなくオプション名のみが記載されるため、CI で --strict を入力し間違えたことを確認できます。

環境変数

少なくとも 1 つのトークンを指定してください。それ以外はすべて任意の設定です。Secret と記された変数は、ログに記録されたり、ツールから返されたりすることはありません。

変数	必須	デフォルト	説明
FB_SYSTEM_TOKEN	いずれか¹	—	シークレット。 システムユーザートークン（Business Manager）。推奨されます。他の2つより優先されます。
FB_ACCESS_TOKEN	いずれか¹	—	シークレット。 Metaユーザーアクセストークン（長期間有効なものを推奨）。
FB_PAGE_TOKEN	いずれか¹	—	シークレット。 長期間有効なページトークン — Business Managerを使用しない場合の代替手段です。特定の1つのページに属します。併せてFB_PAGE_IDにそのページを設定してください。そうしないと、ページスコープのツールでは使用できません。
FB_APP_ID	いいえ	—	MetaアプリIDです。FB_APP_SECRETと組み合わせると、トークンの検査に使うアプリトークンになります。
FB_APP_SECRET	いいえ	—	シークレット。 設定すると、盗まれたトークン単体を使用できないようappsecret_proofが付加されます。
FB_PAGE_ID	いいえ	—	呼び出しでprofileが省略された場合に、ページスコープのツールで使われるデフォルトのページIDです。FB_PAGE_TOKENが唯一の認証情報である場合は必須です（トークンが属するページを指定します）。
FB_API_VERSION	いいえ	v26.0	固定するGraph APIのバージョンです。デフォルト以外の値も指定できますが、テストされているのはデフォルトのみです。
FB_ADS_API_VERSION	いいえ	v26.0	広告ツール用のMarketing APIバージョンです（FB_API_VERSIONとは別のライフサイクルで管理されます）。デフォルト以外の値も指定できますが、テストされているのはデフォルトのみです。
FB_REQUEST_TIMEOUT_MS	いいえ	60000	リクエストごとのタイムアウト（ミリ秒、1～600000）。
FB_HOST_CONCURRENCY	いいえ	4	Graphホストあたりの最大並列リクエスト数（1～64）。
FB_MAX_RESULT_CHARS	いいえ	25000	ツールの結果が切り詰められるまでの文字数上限（500～10000000）。
FB_WRITE_MODE	いいえ	plan	plan（デフォルト）は変更を加えずに書き込み内容をプレビューし、applyは実行します。取り消せない操作や費用が発生する操作の段階には適用されません。
FB_CONFIRM_TOKEN	いいえ	—	シークレット。 プロンプトを表示できないクライアント向けの、制限付き書き込み／支出操作を許可するアウトオブバンド確認トークンです。16文字以上である必要があります。
FB_MEDIA_DIR	いいえ	—	ローカルメディアのアップロード元として許可するディレクトリです。未設定の場合はURLのみとなり、ローカルファイルへのアクセスは無効です。
FB_JOURNAL_PATH	いいえ	XDG / %APPDATA% state path	追記専用のローテーション対応書き込みジャーナルのパス（0600）です。
FB_TOOL_PACKAGES	いいえ	コアプロファイル（ads以外のすべてのパッケージ）	有効にするパッケージまたはプロファイルをカンマ区切りで指定します。coreは常に強制的に有効になり、adsはオプトインです。
FB_PACKAGES_DENY	いいえ	—	FB_TOOL_PACKAGESで有効にされていても除外するパッケージまたはプロファイルです。coreパッケージは常に有効のままです。
FB_PACKAGES_READONLY	いいえ	—	書き込みツールを登録しないパッケージまたはプロファイルです。読み取りツールは引き続き使用できます。
FB_TRANSPORT	いいえ	stdio	stdio（デフォルト）またはhttp（ローカルのエージェントクライアント向けのループバック限定Streamable HTTP）です。
FB_HTTP_TOKEN	httpの場合	—	シークレット。 httpトランスポートに必要なベアラートークンです。設定されていない場合は安全のため動作しません。16文字以上である必要があります。
FB_HTTP_PORT	いいえ	3000	httpトランスポート用のTCPポートです（バインドホストはループバックの127.0.0.1に固定されています）。
FB_AD_ACCOUNT_ID	いいえ	—	オプトインのadsパッケージ用の広告アカウントIDです。
FB_ADS_BUDGET_CEILING	いいえ	—	広告書き込みの予算上限。広告アカウント通貨の最小単位で指定します（0以上の整数、通貨換算なし）。
FB_LOG_LEVEL	いいえ	info	標準エラー出力のログ詳細度です。debug、info、warn、errorを指定できます。
FB_SETUP_TOKEN	いいえ	—	シークレット。 setup-tokenで一度だけ使用される短期間有効なユーザートークンです。CLI引数として渡すより安全な方法です。
FB_PROFILE_<NAME>_PAGE_ID	いいえ	—	名前付きプロファイル用のページIDです（例：FB_PROFILE_BRAND_A_PAGE_ID）。
FB_PROFILE_<NAME>_TOKEN	いいえ	—	シークレット。 対応するFB_PROFILE__PAGE_IDに対する、プロファイルごとの任意のトークン上書きです。
¹ FB_SYSTEM_TOKEN、FB_ACCESS_TOKEN、FB_PAGE_TOKEN のいずれかを少なくとも1つ指定してください。
コメント付きの完全なテンプレートは .env.example にあります。

付与が必要な権限

実際に有効にするパッケージで必要な権限のみを付与してください。以下のスコープは、このサーバーが要求するものです。node build/index.js doctor を実行すると、トークンが実際に持つ権限と照合し、パッケージごとに利用可能／一部利用可能／ブロックの状態を表にして出力します。business_management は意図的にこの一覧に含まれていません。これはセットアップ専用の権限であり、実行時のトークンに含めてはいけません。

パッケージ	必要な Graph 権限
core	pages_show_list pages_read_engagement
reader	pages_read_engagement pages_read_user_content
posts	pages_manage_posts pages_read_engagement
insights	read_insights
moderation	pages_read_engagement pages_read_user_content pages_manage_engagement pages_messaging
messages	pages_messaging pages_manage_metadata
ads	ads_read ads_management

ツールごとのスコープ（継承と記されたツールには、より細かい対応付けがないため、パッケージのスコープが適用されます）

| ツール | 必要な Graph 権限 | | ------------------------------- | --------------------------------------------------------------------- | | `facebook_whoami` | _(なし — トークン自体で十分です)_ | | `facebook_list_pages` | `pages_show_list` | | `facebook_get_page` | `pages_read_engagement` | | `facebook_usage` | _(なし — トークン自体で十分です)_ | | `facebook_list_posts` | `pages_read_engagement` | | `facebook_get_post` | `pages_read_engagement` | | `facebook_list_reels` | `pages_read_engagement` | | `facebook_get_reactions` | `pages_read_engagement` | | `facebook_create_post` | `pages_manage_posts` | | `facebook_create_photo_post` | `pages_manage_posts` | | `facebook_create_video_post` | `pages_manage_posts` | | `facebook_create_reel` | `pages_manage_posts` | | `facebook_update_post` | `pages_manage_posts` | | `facebook_delete_post` | `pages_manage_posts` | | `facebook_list_scheduled_posts` | `pages_read_engagement` | | `facebook_get_video_status` | `pages_read_engagement` | | `facebook_page_insights` | `read_insights` | | `facebook_post_insights` | `read_insights` | | `facebook_reel_insights` | `read_insights` | | `facebook_list_comments` | `pages_read_engagement`、`pages_read_user_content` | | `facebook_get_comment` | `pages_read_engagement`、`pages_read_user_content` | | `facebook_reply_to_comment` | `pages_manage_engagement` | | `facebook_hide_comment` | `pages_manage_engagement` | | `facebook_delete_comment` | `pages_manage_engagement`、`pages_read_user_content` | | `facebook_private_reply` | `pages_messaging`、`pages_read_engagement`、`pages_read_user_content` | | `facebook_block_user` | `pages_manage_engagement` | | `facebook_unblock_user` | `pages_manage_engagement` | | `facebook_list_conversations` | `pages_messaging`、`pages_manage_metadata` | | `facebook_get_conversation` | `pages_messaging`、`pages_manage_metadata` | | `facebook_send_message` | `pages_messaging` | | `facebook_list_campaigns` | `ads_read` | | `facebook_list_adsets` | `ads_read` | | `facebook_list_ads` | `ads_read` | | `facebook_get_ad_object` | `ads_read` | | `facebook_ads_insights` | `ads_read` | | `facebook_ads_report_status` | `ads_read` | | `facebook_update_ad_object` | `ads_management` |

ツール

パッケージは公開単位です。FB_TOOL_PACKAGES でパッケージ全体を有効化または無効化でき、FB_PACKAGES_READONLY でパッケージの読み取り機能を維持したまま、書き込みツールを無効にできます。

3 つのパッケージ変数はすべて、パッケージ と プロファイル（core、all、reader、publisher、moderator、ads）で 1 つの名前空間を共有しており、同じ名前のパッケージとプロファイルがある場合はプロファイルが優先されます。これは FB_PACKAGES_DENY で特に重要です。FB_PACKAGES_DENY=core は、単一の core パッケージではなく、6 つのパッケージからなる core プロファイル を拒否します。その後、core パッケージは強制的に再度有効になります。これは、その ID ツールとレート制限ツールが、対象範囲を絞った後の状態を診断する手段となるためです。どのパッケージやプロファイルにも認識されない名前を指定すると、無視されるのではなく、起動時にエラーになります。

パッケージ	デフォルトで有効	ツール	デフォルトの書き込みモード	対応範囲
core	はい	4 読み取り	—	常時有効な ID、ページの検出、レート制限の診断（読み取り専用）。
reader	はい	4 読み取り	—	ページ自身のコンテンツへの読み取り専用アクセス：投稿（4 つのエッジ）、個別の投稿、リール、リアクションの合計。
posts	はい	2 読み取り + 6 書き込み	plan	ページの投稿、写真、動画、リールの公開、予約、編集、削除（プラン優先：すべての書き込みは適用前にプレビューします）。
insights	はい	3 読み取り	—	ページ、投稿、リールのインサイト：簡潔に再構成した指標系列、集計値、2025 年以降の指標名変更に関するガイダンス（読み取り専用）。
moderation	はい	2 読み取り + 6 書き込み	apply	ページコンテンツへのコメントの読み取りとモデレーション（一覧表示、返信、非表示、削除、非公開返信）、およびブロック済みユーザーリストの管理。
messages	はい	2 読み取り + 1 書き込み	plan	ページの Messenger の会話：受信箱のポーリング、スレッドの読み取り（信頼できないコンテンツはラップされ、添付ファイルはプレースホルダーとして表示）、24 時間以内の非公開返信の送信。デフォルトでプラン優先です。
ads	いいえ（オプトイン）	6 読み取り + 1 書き込み	plan	Marketing API へのアクセス：キャンペーン／広告セット／広告の一覧表示（配信状況の正確な情報を含む）、個別オブジェクトの読み取り、非同期レポート実行によるインサイト、プランで制御されるステータスと予算の管理。デフォルトでは無効です。

7 パッケージに 37 個のツールがあります。 6 つのパッケージはデフォルトで有効で、残りは FB_TOOL_PACKAGES でオプトインできます。read 階層ではデータは変更されません。reversible の書き込みは FB_WRITE_MODE で制御されます。irreversible と spend では、さらに呼び出しごとの apply と、直前に実行したプレビューの plan_id が必要です。環境変数だけでこれらが有効になることはありません。

パッケージ	ツール	Tier	目的
core	facebook_whoami	read	設定されたトークンの背後にあるID（種類、有効性、付与された権限、有効期限）に加え、サーバー、MCP SDK、固定されたGraph APIバージョンを報告します。
core	facebook_list_pages	read	オペレーターが管理するFacebookページ（/me/accounts経由）を一覧表示します：ID、名前、カテゴリ、付与されたタスク、ページトークンが利用可能かどうか。
core	facebook_get_page	read	1つのページのメタデータ（名前、カテゴリ、フォロワー数／ファン数、公開状態、新しいページエクスペリエンスのフラグ）を取得します。
core	facebook_usage	read	直近のGraphレート制限シグナル（X-App-Usage、X-Business-Use-Case-Usage、x-fb-ads-insights-throttle）を使用率として報告するため、制限に達する前に利用を控えられます…
reader	facebook_list_posts	read	ページの投稿を、カーソルページごとに1ページずつ一覧表示します。
reader	facebook_get_post	read	複合ID（facebook_list_postsが返す「{page-id}_{post-id}」）で1つの投稿を取得します。
reader	facebook_list_reels	read	/video_reelsエッジ経由でページのReelsを一覧表示します。Reelsを読み取れるのはここだけです。
reader	facebook_get_reactions	read	1つの投稿へのリアクションを読み取ります：リアクションの種類ごとのtotalsマップ（LIKE／LOVE／CARE／HAHA／WOW／SAD／ANGRY）、全体のtotal、リアクションしたユーザーの一覧。
posts	facebook_create_post	reversible	ページ投稿を作成します：プレーンテキスト、リンク、複数リンクのカードカルーセル、または複数写真のカルーセル。
posts	facebook_create_photo_post	reversible	ページに写真を1枚公開します。必要に応じてキャプションを付けたり、下書きとして保存したり、公開日時を予約したりできます。
posts	facebook_create_video_post	reversible	ページに動画をアップロードします。
posts	facebook_create_reel	reversible	3段階のアップロード（開始 → 転送 → 完了）を通じてFacebook Reelを公開します。video_stateはPUBLISHED、DRAFT、SCHEDULEDから明示的に指定します。
posts	facebook_update_post	reversible	アプリ自体が作成したページ投稿を編集するか、予約投稿のライフサイクルを進めます。
posts	facebook_delete_post	irreversible	アプリ自体が作成したページ投稿を完全に削除します。予約投稿も対象で、キャンセルする唯一の方法です。
posts	facebook_list_scheduled_posts	read	後で公開するようにキューに登録されたページ投稿を一覧表示します。各投稿の公開時刻はUTCとページの現地時間で示されます。
posts	facebook_get_video_status	read	Metaのパイプラインで動画がどの段階にあるか（アップロード中、処理中、準備完了、エラー）を確認します。
insights	facebook_page_insights	read	1つのページのGraphインサイトを、コンパクトなフラット形式で読み取ります：データポイントと指標ごとに1行（{metric, date, value}、アクションタイプ別の指標にはbreakdownも付加）…
insights	facebook_post_insights	read	公開済みの1つの投稿のGraphインサイト（post_media_view、post_clicks、post_reactions_by_type_total、動画指標など）を、同じコンパクトなフラット形式で読み取ります…
insights	facebook_reel_insights	read	/{video-id}/video_insightsから1つのReelのGraphインサイトを読み取ります。Reel指標が実際に存在するエッジであり、facebook_post_insightsでは取得できません。
moderation	facebook_list_comments	read	投稿、写真、動画、または別のコメントへのコメントを、デフォルトでは新しい順に一覧表示します。
moderation	facebook_get_comment	read	IDで1つのコメントを読み取ります。必要に応じて返信も取得し、非公開返信がまだ可能かどうか（7日間の期間）を報告します。
moderation	facebook_reply_to_comment	reversible	コメントに公開返信を投稿します。スレッドを閲覧できるすべての人に表示されます。
moderation	facebook_hide_comment	reversible	1回の呼び出しで最大50件のコメントを非表示または再表示します（hidden:trueで非表示、hidden:falseで元に戻します）。
moderation	facebook_delete_comment	irreversible	最大50件のコメントを完全に削除します。
moderation	facebook_private_reply	irreversible	コメント投稿者に非公開メッセージを送信します。
moderation	facebook_block_user	reversible	最大50件のPSIDをページのブロックリストに追加します。対象者はページにコメントしたり、ページにメッセージを送ったりできなくなります。
moderation	facebook_unblock_user	reversible	最大50件のPSIDをページのブロックリストから削除し、コメントやメッセージを送る機能を復元します。
messages	facebook_list_conversations	read	ページのMessenger会話（platform=messengerのみ。Instagramのスレッドは対象外）を一覧表示します：ID、updated_time、unread_count、message_count、最新メッセージの抜粋。
messages	facebook_get_conversation	read	Messengerのスレッドを新しいメッセージから順に読み取ります：送信者、タイムスタンプ、方向、本文に加え、画像、スタンプ、ファイル、共有リンクの型付きプレースホルダー（添付ファイル…
messages	facebook_send_message	reversible	標準の24時間メッセージ送信期間内に、ページとしてプレーンテキストの非公開Messengerメッセージを1件返信として送信します（messaging_type=RESPONSE）。
ads	facebook_list_campaigns	read	1つの広告アカウントのキャンペーンを、カーソルページごとに一覧表示します。
ads	facebook_list_adsets	read	1つの広告アカウントの広告セットを、カーソルページごとに一覧表示します。
ads	facebook_list_ads	read	1つの広告アカウントの個別広告を、カーソルページごとに一覧表示します。
ads	facebook_get_ad_object	read	IDで1つのキャンペーン、広告セット、または広告を読み取ります。
ads	facebook_ads_insights	read	広告アカウント、キャンペーン、広告セット、または広告のパフォーマンス数値（インプレッション、クリック数、消化金額、リーチ、cpc、ctr）を読み取ります。
ads	facebook_ads_report_status	read	非同期インサイトレポートの実行状況を確認し、fetch_results:trueを指定すると、完了後にその行を読み取ります。
ads	facebook_update_ad_object	spend	広告オブジェクトを一時停止または再開するか、予算を変更します。

比較

特定時点の調査（2026-07-21）です。詳しい分析は docs/analysis/02-market-and-positioning.mdをご覧ください。

プロジェクト	対象	言語	ライセンス	配布形態	備考
facebook-mcp（本プロジェクト）	ページ／オーガニック＋広告	TypeScript	MIT	npm＋MCPB バンドル	複数ページ、計画してから適用する書き込み、編集、MCP アノテーションと outputSchema
Meta's official hosted Ads MCP	広告のみ	ホスト型	Meta ToS	mcp.facebook.com/ads	ビジネス向け OAuth、開発者アプリ不要、約29個のツール。無料。
pipeboard-co/meta-ads-mcp	広告	Python	BUSL-1.1	ホスト型リモート	市場をリード（約1.1k ★）、42個のツール。OSI オープンソースではありません。
HagaiHen/facebook-mcp-server	ページ	Python	MIT	ソースのみ	他に注目すべきページ向けサーバーはこれだけです。27個のツール、単一ページ、テストなし。

**広告だけが必要なら、Meta の公式サーバーをお使いください。**無料で、独自の 開発者アプリは不要です。ベンダーが保守しており、このプロジェクトでは到底 カバーできない範囲の広告機能に対応しています。ここに ads パッケージがある 理由は1つだけです。単一のトークンと設定で、広告をページ、モデレーション、 メッセージ機能と組み合わせ、同じ支出制御を適用するためです。そのため、 デフォルトでは無効になっています。広告は、このプロジェクトを インストールする理由ではありません。

このプロジェクトをインストールする理由は、ページ機能にあります。複数ページ、 動画やリールのアップロード、予約投稿のライフサイクル、指標の名前変更や 廃止を通知するインサイト、コメントやメッセージのモデレーションを備え、 型付けされ、テスト済みで、MIT ライセンスのサーバーがすべてローカルマシン上で 動作します。

既知の制限事項

現状に即した、事実に基づく、意図的に率直な説明です。

• Graph API に対するライブ検証はありません。 ここにある内容は、Meta のサーバーで検証されていません。フィクスチャには API のドキュメントに記載された動作が反映されていますが、実際の動作は異なる可能性があります。
• 公開済みですが、まだ登場したばかりです。 0.7.0 はプロベナンス付きで npm に公開されており、.mcpb バンドルはリリースに添付済みで、MCP Registry への掲載も有効です。ただし、CI 以外でインストール手順を最初から最後まで実行した人はいません。クライアントごとの状況については、クライアント互換性をご覧ください。
• プロンプトを表示できないクライアントでは、オペレーターのトークンが必要です。 irreversible と spend の書き込みには、呼び出しごとの apply と plan_id に加えて、モデル自身では提示できない、別経路での確認が必要です。クライアントが MCP の elicitation 機能に対応している場合、サーバーはその機能を通じて人間のオペレーターに確認を求めます。対応していない場合、呼び出し元は FB_CONFIRM_TOKEN の値をツールの confirm_token 引数に渡す必要があります。どちらの方法も使えない場合、これらのツールは confirmation_denied を返します。
• アップロードの進行状況は、クライアントが要求した場合にのみ取得できます。 分割アップロードされる動画とリールは、チャンクごとに notifications/progress を送信します。ただし、MCP 仕様で定められているとおり、呼び出し元がリクエストに progressToken を指定した場合に限ります。指定しないクライアントには進捗が届かず、長時間のアップロードは単に遅く感じられます。
• インサイトの指標は予告なく変更されます。 Meta は、3 回（2024-09、2025-11、2026-06-15）にわたって多数のページ／投稿指標を廃止・改名しました。インサイトツールは要求された指標を分類し、改名または廃止されている場合はその旨を通知するため、何も返さずに済ませることはありません。ただし、元データの喪失は Meta によるものであり、それを元に戻せるラッパーはありません。
• メッセージ機能には、Meta の 24 時間ルールが適用されます。 24 時間以上やり取りが途絶えた会話には、メッセージタグなしでは返信できません。このサーバーがその制限を回避することはありません。
• メンテナーは 1 人で、バージョンは 1.0 未満です。 1.0 までは、非推奨期間を設けずにインターフェースが変更される場合があります。

対象外

「Facebook MCP サーバー」に期待されがちですが、このサーバーでは対応していない機能です。インストールしてから気づくのではなく、30 秒で対象外だと判断できるように記載しています。

• 個人プロフィールとグループ。 個人のタイムラインへの投稿に API はありません。また、グループ API は 2024 年 4 月に廃止されました。このサーバーが操作するのはページのみです。
• Instagram、Threads、WhatsApp。 製品も必要な権限セットも異なります。将来、関連する別のサーバーが作られる可能性はありますが、このサーバーでは対応しません。
• Webhook／リアルタイム取り込み。 ローカルの stdio サーバーには、コールバックを受信するための公開 URL がありません。設計上、読み取りはポーリングで行います。
• オーガニック投稿の宣伝（/{page-id}/promotions）。オーガニック投稿から広告への連携は、最も要望の多い機能ですが、1.0 以降まで意図的に保留しています。広告パッケージに加え、十分に検討した支出制御が必要で、後付けで済むものではありません。
• ページストーリーズ。 公開用エンドポイントは存在しますが、検証されていません。ストーリーズは 1.0 での提供を約束しておらず、実際の動作が確認されるまで対象外です。
• イベント、ライブ動画、アルバム／フォトライブラリの読み取り、ページプロフィールの編集、オーガニック投稿のターゲティング。 実在するエンドポイントですが、このサーバーが対応するとしている投稿／動画／リール／スケジュール／モデレーションの範囲外です。
• マルチテナントまたはホスト型の運用、他の事業者の広告アカウントの提供。 この設計は、Standard Access を使用し、自身のアセットを自身のマシンで扱う 1 人のオペレーターを対象としています。それ以外には App Review と Business Verification が必要となり、別の製品になります。

詳しい理由については、 docs/analysis/01-goals-and-scope.mdをご覧ください。

オペレーターとしての責任

このサーバーは、アプリとトークンを通じて、Meta があなたに帰属させる操作を自動化します。操作を自動化しても、その操作に適用されるルールから免除されるわけではありません。

• Meta のプラットフォーム規約と開発者ポリシーは引き続き適用されます — スパム対策や自動化された行動に関するルールも含まれます。大量または反復的な投稿、コメント、メッセージ送信は、ページの制限やアプリの無効化につながる可能性があり、モデルがタイミングを選んだという事実は免責理由になりません。
• Messenger の自動化は開示する必要があります。 Meta は、ユーザーが自動化されたシステムと会話していることを認識できるよう求めています。メッセージングツールを人々への返信に使用する場合は、そのことを伝えてください。
• コンテンツと同意に関する責任はあなたにあります。 ツールは指定された内容をそのまま公開します。その内容を使用する権利があるかどうか、また非公開の返信や DM の場合は相手が連絡を予期しているかどうかを判断することは、ラッパーにはできません。
• これは法的助言ではありません。 高機能な自動化ツールには義務が伴うという率直な注意書きであり、このプロジェクトはそのことをあらかじめ伝える方針です。

セキュリティ面での対応については SECURITY.mdを参照してください。

ロードマップ

作業状況はfacebook-mcp ロードマップボードで公開されており、リリースマイルストーンごとにまとめられています。

マイルストーン	対象範囲
v0.1.0 — コア	基盤 + core ツール、ライブスモークハーネス
v0.2.0 — リーダーと公開	投稿/Reels の読み取り、公開、スケジュール設定、写真/動画/Reels メディア
v0.3.0 — インサイトとモデレーション	ページ/投稿のインサイト、コメントのモデレーション、ブロック
v0.4.0 — メッセージング	会話とメッセージ送信
v1.0.0 — 安定版	ライブ検証、メタデータ SSOT、リリース工程、npm への公開
v1.1.0 — 広告	広告の読み取りと制御、オプトイン方式でデフォルトでは無効

v1.0.0 には ads パッケージは含まれません — 意図的なものです。製品の中心は Pages の機能であり、ads はオプトイン方式でデフォルトでは無効となり、1.1.0 で追加されます。そのコードはすでに作業ツリーにあります。だからこそ、このマイルストーンが実装ではなく_検証_を対象としているのです。マイルストーンが完了するのは、機能が Meta のサーバーに対してライブ検証され、リリースされたときであり、コードが追加されたときではありません。バージョン対応を定めるドキュメントは docs/analysis/10-v1-release-definition.mdです。

各項目の設計は、事前にdocs/analysis/にまとめられています — ロードマップはその資料群から導かれたものであり、資料群に取って代わるものではありません。

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

• 3つのホストに限定。 接続先は graph.facebook.com、graph-video.facebook.com および rupload.facebook.com のみです。許可リストはコード内で固定されており、 ユーザーは変更できないため、リダイレクトやホスト名の入力ミスによって トークンが知らないうちに送信されることはありません。
• 計画と適用による書き込み制御。 書き込みはデフォルトで plan（変更を加えない プレビュー）になり、apply で実行されます。例外は moderation で、コメントの非表示は 大量に行われ、元に戻せる操作のため、デフォルトで apply になります。 FB_WRITE_MODE はパッケージのデフォルトをどちらの方向にも完全に上書きするため、 モードはツールごとの約束ではなく、運用担当者が決定します。このモードでは制御できない操作： 取り消せない操作と支出を伴う操作には、常に別経路での確認が必要です。また、実際の利用者に 表示される操作（投稿やリールの公開、予定投稿の早期公開、DMの送信）には、該当する呼び出しそのものの プレビューに紐づいた plan_id も必要です。どちらも環境変数で回避することはできません。
• 一元化された秘匿情報のマスキング。 秘密情報の値は、ログ、エラー、ツールの結果、 書き込みジャーナルに渡る前の単一の箇所で除去されます。ページアクセストークンは 真偽値に変換され、その値がペイロードに含まれることはありません。
• テレメトリーなし、ローカル優先。 サーバーは stderr にのみログを出力し、 データを収集せず、外部に情報を送信することもありません。http トランスポートは ループバック（127.0.0.1）にのみバインドし、FB_HTTP_TOKEN がない場合は フェイルクローズします。

セキュリティモデルの全容と脆弱性の報告方法については、SECURITY.md をご覧ください。

ドキュメント

• 設計資料一式 — 実装前の分析の全容は docs/analysis/ にあります。目標と範囲、市場での位置づけ、Graph API の概要、認証とセキュリティのモデル、 アーキテクチャ、ツールカタログ、リスク、ロードマップ、例外的なケース、v1.0 のリリース定義、 および開発を推進する並行タスクの分解が含まれます。
• 運用手順書 — 運用手順は docs/runbooks/ にあります。
• エラーカタログ — サーバーが分類するすべての Graph エラー、再試行の有無、 および対処方法については、docs/error-catalog.md をご覧ください。
• ドキュメントサイト — ivanbbaev.github.io/facebook-mcp。

上記の環境変数の表、パッケージ／ツールの表、権限の表、およびエラーカタログは、 npm run metadata によってコードから生成されます。内容に差異があると CI は失敗します。

サポート

GitHub を通じて、可能な範囲で単独メンテナーがサポートを提供しています。 バグ、機能リクエスト、セキュリティ報告の提出方法は SUPPORT.md をご覧ください。

このプロジェクトは、私自身の時間を使って開発・保守しています。役に立った場合は、 ご支援いただけると継続の助けになります。

• GitHub Sponsors — 単発または定期的な支援が可能で、 プラットフォーム手数料はかかりません。
• Ko-fi — 手軽な単発支援（PayPal にも対応）です。 GitHub アカウントをお持ちでない方はこちらをご利用ください。
• Donatree — 地域別の決済方法を含む、あらゆる寄付方法を 1ページにまとめています。

寄付によって優先サポートや SLA が提供されることはありません。SUPPORT.md をご覧ください。 金銭的な支援が難しい場合は、リポジトリにスターを付けたり、質の高いバグ報告を提出したりすることも 同じくらい役立ちます。

商標

これはコミュニティによって構築された独立プロジェクトであり、Meta Platforms, Inc. とは 提携、推奨、スポンサー関係にありません。Facebook、Meta、および関連するマークは Meta Platforms, Inc. の商標であり、互換性を示す目的に限ってここで使用しています。

ライセンス

MIT © 2026 Ivan Baev