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

(a) Via npx

Configure credentials first (see below), then run the pre-flight check:

npx -y @ivanbaev/facebook-mcp doctor   # token, scopes, package matrix

Register it with your MCP client:

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

Claude Code plugin (installs the server wired up):

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

Claude Desktop takes the .mcpb bundle attached to the latest release. 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.7.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 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:

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

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.