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. Not yet published to npm. The foundation — HTTP client, auth, write gating, transports, tool registry — is complete and tested; 4 of the 35 planned tools are live today (the read-only core package). The publishing, reading, moderation and messaging packages are next. Interfaces and scope may change until the first tagged release. See the roadmap for what lands when.

Contents: Features · Requirements · Setup · Configure credentials · Tools · Roadmap · Security notes · Documentation · Support · Trademark · License

Features

The default profile exposes a deliberately small, curated tool surface — each tool wraps a real, verified 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.

Related MCP server: io.github.anthonyjbolo/mcp-fb-publisher

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) From source (current)

The package is not on npm yet, so build from a clone:

git clone https://github.com/IvanBBaev/facebook-mcp.git
cd facebook-mcp
npm install
npm run build
node build/index.js   # or: ./bin/facebook-mcp.mjs

Configure credentials (see below), then point your MCP client at that command.

(b) Via npx (after the first release)

Both snippets below become available after the first published release — the package is currently unpublished.

Register the server with an MCP client (Claude Desktop, VS Code Chat, the Inspector…) by pointing its command at npx:

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

Claude Code plugin (installs the server wired up):

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

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.

Grant only the permissions the packages you enable actually need (least-privilege), 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).

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.

Tools

The always-on core package ships four read-only tools today. The reader, posts, insights, moderation, messages and ads packages are on the roadmap, and this table will grow as they land.

Roadmap

Work is tracked publicly on the facebook-mcp roadmap board and grouped into release milestones:

The design behind each item is written up in advance in docs/analysis/ — the roadmap is a consequence of that corpus, not a replacement for it.

Security notes

• Three-host fence. Only graph.facebook.com, graph-video.facebook.com and rupload.facebook.com are ever contacted — the allowlist is fixed in code and not user-configurable, so a redirected or mistyped host cannot silently receive a token.

• Plan-and-apply write gating. Writes default to plan (a non-mutating preview); apply executes. Irreversible and spend actions additionally require an out-of-band confirmation and are never bypassed by an env flag.

• Single-choke-point redaction. Secret values are stripped at one place before anything reaches logs, errors, tool results or the write journal; Page access tokens are derived to a boolean and their values never enter a payload.

• No telemetry, local-first. The server logs only to stderr, collects nothing, and phones home nowhere. The http transport binds loopback (127.0.0.1) only and fails closed without FB_HTTP_TOKEN.

See SECURITY.md for the full model and vulnerability reporting.

Documentation

• Design corpus — the full pre-implementation analysis lives in docs/analysis/: goals & scope, market positioning, Graph API landscape, auth & security model, architecture, tool catalog, risks, roadmap, corner cases, the v1.0 release definition, and the parallel task-breakdown that drives development.

• Documentation site — ivanbbaev.github.io/facebook-mcp.

Support

Best-effort, single-maintainer support runs through GitHub — see SUPPORT.md for how to file bugs, feature requests and security reports.

This project is built and maintained in my own time. If it helps, a tip keeps it going:

• GitHub Sponsors — one-off or recurring, no platform fee.

• Ko-fi — quick one-off support (also accepts PayPal), the fallback for anyone without a GitHub account.

• Donatree — every donation method on one page, including local payment options.

Donating buys no priority support and no SLA — see SUPPORT.md. If money is not an option, starring the repository or filing a good bug report helps just as much.

Trademark

This is an independent, community-built project and is not affiliated with, endorsed by, or sponsored by Meta Platforms, Inc. Facebook, Meta and related marks are trademarks of Meta Platforms, Inc., used here only nominatively to indicate compatibility.

License

MIT © 2026 Ivan Baev