Drive your Facebook Page from your AI assistant.

Three things it does, in one place

Your assistant calls a small, curated set of tools. Each one wraps a real, verified Graph API capability — not every raw edge. The three below are designed and scheduled, not yet shipped — they land in v0.2.0 and v0.3.0.

{
  "message": "We just shipped v1 🎉",
  "link": "https://example.com/launch",
  "published": true
}

→ PREVIEW · resolves Page, checks perms
→ "The post was NOT published."
→ call again with { "apply": true }

{
  "object": "post",
  "metrics": ["post_impressions",
              "post_reactions_by_type"]
}

→ post_impressions            1,204
→ post_reactions_by_type        86
→ paging cursors stripped of tokens

{
  "comment_id": "102…847_9911",
  "hidden": true
}

→ PREVIEW · before-state: visible
→ apply → comment hidden
→ recorded to local write journal
    (metadata only, secrets redacted)

What is the Model Context Protocol?

The Model Context Protocol (MCP) is an open standard that lets AI assistants call external tools through a uniform interface. An MCP server exposes a set of typed tools; an MCP client (your assistant) discovers them and calls them on your behalf.

facebook-mcp is one such server. It runs on your own machine, talks only to Meta's Graph API, and turns Page operations — publishing, insights, moderation — into tools your assistant can use. Because it runs locally with your token, there is no third-party service in the middle: your credentials never leave your machine, and the server never phones home.

Capabilities

Grouped into packages you can enable or restrict. The default profile is publishing, reading, insights, moderation and messages — with ads deliberately left off. The Ships in column is the honest part: only core is live today, the rest is designed and scheduled.

Quick start

There is no npm package yet, so you run it from source. Three steps to a working server, then point your MCP client at it.

{
  "mcpServers": {
    "facebook": {
      "command": "node",
      "args": ["/abs/path/facebook-mcp/build/index.js"],
      "env": {
        "FB_ACCESS_TOKEN": "EAA…",
        "FB_PAGE_ID": "1234567890",
        "FB_APP_SECRET": "…"
      }
    }
  }
}

{
  "mcpServers": {
    "facebook": {
      "command": "npx",
      "args": ["-y", "@ivanbbaev/facebook-mcp"],
      "env": {
        "FB_ACCESS_TOKEN": "EAA…",
        "FB_PAGE_ID": "1234567890"
      }
    }
  }
}

Not available yet — shown here as the intended shape once the package ships. Track progress on GitHub.

Credentials

You bring your own Meta developer app and a token for a Page you administer. facebook-mcp uses the least privilege that works — and no App Review, because you operate your own assets.

Two token routes

Environment variables

No Meta App Review is required for an admin operating their own Page. Start read-only, confirm the topology, then enable writes when you are ready.

Architecture

A thin, lint-enforced stack. Each layer may only import the one below it, so tools can never reach around policy straight to the network.

The three-host fence

There is exactly one vendor, so the HTTP client hard-codes a fixed host allowlist — there are no user-configurable hosts. Every request, including chunked media uploads, goes through one choke-point that can only reach these three:

One fbRequest() entry point covers all three wire protocols — JSON / query-string reads and simple writes, multipart FormData for direct binary uploads, and raw-binary rupload for chunked resumable video and Reels — so no media path can bypass auth, redaction or the host fence.

Security & safety

Publishing to a real audience is the most consequential thing this server does, so safe-by-default is non-negotiable.

Defense in depth

• appsecret_proof (HMAC-SHA256) is attached to every Graph call.
• Response scrubbing recursively strips every paging object and token-bearing URL before a payload leaves the process.
• SSRF containment — the fixed host allowlist means no request can be steered to an arbitrary host; local file uploads are off unless you explicitly set FB_MEDIA_DIR (realpath-confined, no cross-host redirects).
• HTTP transport fails closed — it refuses to start without FB_HTTP_TOKEN, binds 127.0.0.1 only, validates the Origin header, and constant-time checks the bearer on every request.
• Ambiguous writes are never auto-retried — Graph has no idempotency keys, so a publish/send/delete whose outcome is unknown is surfaced for you to verify, never blindly replayed.

FAQ

Is this affiliated with Meta?

No. This is an independent, community-built project and is not affiliated with, endorsed by, or sponsored by Meta Platforms, Inc. "Facebook" and "Meta" are used only nominatively, to indicate what the server is compatible with.

Which credentials does it need?

A Meta developer app plus one access token — either a never-expiring System User token from Business Manager, or a long-lived Page token. The app secret is used to compute appsecret_proof. Because you administer your own Page, no App Review is required.

Is it safe to let it write to my Page?

Writes are gated. Every write tool first returns a dry-run preview and performs zero network mutations; you approve with an explicit apply. Irreversible actions (delete) and spend actions (ads) always require a per-call confirmation and are never bypassed by an environment flag. Starting read-only is recommended.

What actually works today?

The foundation — HTTP client, auth, write gating, transports, tool registry — is implemented and tested, and the read-only core package ships four tools: facebook_whoami, facebook_list_pages, facebook_get_page and facebook_usage. Everything else on this page is designed and scheduled; see the roadmap board for what lands when.

When will it be published to npm?

Not yet. facebook-mcp is pre-1.0 and in active development — the design is complete and documented while implementation is in progress. An npm package will ship with the first tagged release; until then you run it from source. Progress is tracked in the milestones.

Which MCP clients does it work with?

Any client that speaks MCP over stdio — for example Claude Desktop, Claude Code, VS Code and Cursor. An optional loopback-only Streamable HTTP transport is available for advanced setups.

Support the project

facebook-mcp is MIT-licensed, free, collects nothing and is built by one maintainer in their own time. There is no paid tier and never will be — if it saves you an afternoon, a tip is what funds the next milestone.