Facebook MCP Server

facebook-mcp — Facebook Pages MCP Server

📖 Documentation site →

A local-first TypeScript Model Context Protocol (MCP) server for the Meta Graph API, focused on Facebook Pages — publishing, reading & insights, and comment/message moderation — driven from an MCP client (Claude, VS Code, the Inspector…) and operated locally by a Page admin using their own Meta developer app. Least-privilege tokens, plan-and-apply write safety, and no telemetry.

🚧 Status: pre-1.0, in active development. Published on npm as @ivanbaev/facebook-mcp — and the version number is the warning.

All seven tool packages are implemented — see the tool table for the exact surface. Nothing has been verified against the live Graph API yet. Every test in this repository runs against fakes and recorded fixtures behind a network fence that throws on a real fetch, so "the tests pass" means "the code does what the fixtures say", not "Meta accepted it". A live smoke harness exists (scripts/smoke/) but has not been run against a real Page as part of any released state. Treat every capability below as implemented but unproven, expect breaking changes until 1.0, and read Known limitations before you rely on anything.

Contents: Features · Requirements · Setup · Client compatibility · Configure credentials · Permissions · Tools · How this compares · Known limitations · Not in scope · Your responsibilities · Roadmap · Security notes · Documentation · Support · Trademark · License

Features

Implementation status only — see the status note above for what "implemented" does and does not mean.

The default profile exposes a deliberately small, curated tool surface — each tool wraps one real capability rather than mirroring every Graph edge.

• Local-first, no telemetry. Only three Meta hosts are ever reached (graph, graph-video, rupload); nothing phones home.
• Least-privilege credentials. Works with a never-expiring System User token (Business Manager) or a long-lived Page token — no App Review required for an admin operating their own assets.
• Safe writes. Tiered plan-and-apply gating; irreversible and spend actions require out-of-band confirmation and are never bypassed by an env flag.
• Secret hygiene. Value-based redaction at a single choke-point across logs, errors, tool results, and the write journal.
• Layered architecture. Lint-enforced core ← api ← mcp ← tools layering, tools-as-data with a central package registry.

Requirements

• Node.js ≥ 22 (enforced by engines and a runtime guard in the launcher; the project targets the version in .nvmrc).
• A Meta (Facebook) developer app — a Business-type app at Standard Access is enough; no App Review is needed to operate your own assets.
• A Facebook Page (and, for the opt-in ads package, an ad account) you administer.

Setup

The first run is five steps, in this order. Budget about 20 minutes; most of it is Meta's app UI. docs/runbooks/onboarding.md is the long form with troubleshooting.

1. Meta app — create a Business-type app at https://developers.facebook.com/apps and note its App ID and App Secret (Settings → Basic). setup-token needs both.

2. Short-lived token — in the Graph API Explorer pick your app, User Token, tick the scopes you need (at least pages_show_list and pages_read_engagement), and Generate Access Token. It lives 1–2 hours, so do step 3 right away.

3. Exchange it and write the env file — setup-token swaps it for a ~60-day token, resolves your Page and writes the env file:

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

   Success is status: completed in the Run block and status: written in the Env file block. The file lands at ~/.config/facebook-mcp/.env ($XDG_CONFIG_HOME if set) or %APPDATA%\facebook-mcp\.env on Windows, mode 0600. The server reads it on every start, so the client config below needs no env block. More than one Page? Re-run with --page=<id> --force.

4. Pre-flight — every package you plan to use should be usable:

   npx -y @ivanbaev/facebook-mcp doctor
   

5. Register the server with your client and make the first call — see the next two subsections, then ask the client to "run facebook_whoami". A reply naming your token type and Page is the first successful tool call.

The doctor and setup-token reports name commands in the form you launched with (npx -y @ivanbaev/facebook-mcp …, facebook-mcp … after a global install, or node build/index.js … from a source checkout). --help writes facebook-mcp …; substitute your launch form. Every subcommand takes --help without touching the network.

(a) Via npx

Claude Code — one command, then check /mcp inside a session:

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

It is registered for the current project directory by default; add --scope user to have it everywhere. Or install it as a plugin, which wires up the same command:

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

Claude Desktop — Settings → Developer → Edit Config opens claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\). Add the server, save, then quit and restart Claude Desktop:

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

Claude Desktop does not load your shell profile. If Node comes from a version manager (nvm, fnm, asdf) and the server fails to start, put the absolute path of npx (which npx) in command.

Any other stdio client takes the same command / args pair — see Client compatibility.

Claude Desktop bundle (alternative) — the .mcpb attached to the latest release installs by double-click. Its settings form lists every credential as optional: leave them blank to use the env file from step 3 (a blank field never overrides it). It carries a build-provenance attestation, so you can prove it came out of this repository's workflow before you install it:

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

(b) From source

For development, or to run a commit that is not released yet:

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

Point your MCP client at that command with an absolute path. The env block is optional — without it the server reads the env file, and a non-blank value here overrides the file:

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

(c) Instagram alongside: the sibling server

This server stays Pages-only. Instagram professional accounts are covered by the separate instagram-mcp-ai server (publishing, media, comments, insights, DMs). Run both side by side; each keeps its own credentials and env file (~/.config/instagram-mcp-ai/.env for Instagram, set up with npx instagram-mcp-ai login), so neither config below needs an env block.

Claude Code:

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

Claude Desktop (claude_desktop_config.json):

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

The two servers share nothing at runtime: a post to a Page and a post to Instagram are two tool calls, each with its own preview. Tool names do not collide (facebook_* here).

Client compatibility

This is a standard stdio MCP server with no client-specific code, so it should work anywhere the protocol does. "Should" is the operative word: the table records the configuration each client needs and whether that path has actually been exercised — not a promise.

What is verified, by automated test:

• stdio framing — a test spawns the built server as a real subprocess, runs the full initialize → tools/list → tools/call handshake over pipes, and asserts that stdout carries protocol frames only (all logging goes to stderr).
• Tool contracts — every tool's input/output schema, annotations, write tier and error mapping are unit-tested against fakes and recorded fixtures.
• The HTTP transport — loopback binding, bearer-token rejection and session handling, again against a real local server.

None of that involves an MCP client or the Meta API. If you get it working with a client, say so in an issue — that is how this table turns into ✅.

Platform notes

CI runs the full check on Linux (Node 22/24/26) and Windows (Node 22). macOS is the primary development platform but is not in CI. Paths for the env file, the write journal and FB_MEDIA_DIR follow XDG on POSIX and %APPDATA% on Windows.

Configure credentials

facebook-mcp authenticates with a token you already control — there is no App Review, no OAuth callback server, and no hosted component. Provide at least one of the token variables below; the most specific wins (FB_SYSTEM_TOKEN → FB_ACCESS_TOKEN → FB_PAGE_TOKEN):

• FB_SYSTEM_TOKEN — a never-expiring System User token (Business Manager). Recommended: it does not expire and is scoped to the assets you assign it.
• FB_ACCESS_TOKEN — a Meta user access token (a long-lived one preferred).
• FB_PAGE_TOKEN — a long-lived Page token, the no-Business-Manager fallback. It belongs to exactly one Page, so set FB_PAGE_ID to that Page alongside it (doctor / facebook_whoami reports it as the acting Page).

Grant only the permissions the packages you enable actually need (full list below), and set FB_APP_SECRET so appsecret_proof is attached to every call — that makes a stolen bare token unusable on its own. Settings are read from an env file at the XDG/%APPDATA% config path, or from real environment variables (which take precedence).

If you would rather not assemble the env file by hand, run npx -y @ivanbaev/facebook-mcp setup-token (node build/index.js setup-token from source) — the guided flow exchanges and classifies a token and writes the env file for you (--page=<id>, --env-file=<path>, --force to overwrite, --no-write/--dry-run to rehearse; pass the token via FB_SETUP_TOKEN rather than on the command line; the exchange also needs FB_APP_ID and FB_APP_SECRET). See docs/runbooks/onboarding.md for the full walkthrough.

Then run doctor (npx -y @ivanbaev/facebook-mcp doctor) before anything else: it inspects the token, reports type, expiry and granted scopes, and prints a per-package usable / partial / blocked matrix so you find a missing permission before a tool call does. It ends with a one-line verdict over everything it found.

The doctor is a report, so it exits 0 whatever it finds — a wrapper that runs it for the text keeps working. Add --strict to make it a gate instead:

UNKNOWN outranks WARN on purpose: "nothing was established" must not hide behind "degraded". A platform without POSIX permission bits raises no finding for the credential file — there is no chmod to recommend there, and a warning nothing can clear would make --strict permanently red on Windows.

node build/index.js --version (or -v) prints the server, Node and MCP SDK versions on one line and exits — it needs no credential, so it still answers on an install that cannot start:

facebook-mcp 0.8.0 (node v22.23.0, darwin arm64, sdk 1.32.1)

The bare server version is always the second field, so --version | awk '{print $2}' keeps working. The same three versions plus the pinned Graph API version are reported by facebook_whoami in its server object (name, version, apiVersion, sdkVersion). --help (or -h) prints the command summary and a first-run recipe to stdout and exits 0, again without reading any credential; setup-token --help and doctor --help do the same instead of running. doctor, setup-token, --version and --help are the only arguments that exit on their own; anything else starts the stdio server and waits on JSON-RPC. An argument doctor does not recognise (say --stric) never gates, but the report names it — option names only, never a value — so a mistyped --strict in CI is visible.

Environment variables

Provide at least one token; everything else is optional tuning. Variables marked Secret are never logged or returned by a tool.

¹ Provide at least one of FB_SYSTEM_TOKEN, FB_ACCESS_TOKEN or FB_PAGE_TOKEN. A full, commented template lives in .env.example.

Permissions you need to grant

Grant only what the packages you actually enable require. The scopes below are the ones this server asks for; node build/index.js doctor compares them against what your token really has and prints a per-package usable / partial / blocked matrix. business_management is deliberately not in this list — it is a setup-only permission that should never ride on a runtime token.

Tools

Packages are the unit of exposure: you enable and disable whole packages with FB_TOOL_PACKAGES, and FB_PACKAGES_READONLY drops a package's write tools while keeping its reads.

Documentation truncated — see the full README on GitHub.