Facebook Mcp

facebook-mcp — an MCP server for Facebook Pages

📖 Documentation site →

A local-first, MIT-licensed TypeScript Model Context Protocol (MCP) server for developers who run their own Facebook Page(s) from an MCP client such as Claude Code, Claude Desktop, VS Code or Cursor. It talks to the Meta Graph API through your own Meta developer app and your own token: publishing, reading and insights, comment moderation and Messenger replies. Writes return a preview first by default (plan-and-apply), and the server sends no telemetry.

Things you could ask your agent once it is set up (the tools exist; see Status for what has been verified):

• "Draft a post with this photo and schedule it for Friday 9:00 — show me the preview first."
• "Triage the unanswered comments on last week's posts."
• "Give me this week's Page report."

Not for you if you do not want to create a Meta developer app and handle an App ID, an App Secret and a token yourself — hosted social-media connectors with a one-click login are a better fit for that. It is also not for personal profiles, Groups, Instagram (there is a sibling server) or a hosted service for other people's Pages — see Not in scope.

Status

🚧 Pre-1.0, and not yet verified against a live Page. The latest release is @ivanbaev/facebook-mcp 0.8.0 on npm. This README describes main, which can be ahead of that release; unreleased changes are listed in changes/unreleased/.

• Implemented, not live-verified. All 69 tools in the tool table are implemented. 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 for any release.
• No client verified by hand. CI starts the packed server with npx on Linux, macOS and Windows, but no person has walked an install end-to-end in any MCP client yet — see Client compatibility.
• Experimental tools. Some tools are marked experimental (list under Not in scope): they may change in any minor release, even after 1.0.
• Breaking changes are planned. 0.9 changes tool contracts (see Roadmap). Read Known limitations before you rely on anything.

Contents: Status · 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 Status for what "implemented" does and does not mean. "Experimental" follows the experimental tier.

Each tool wraps one capability rather than mirroring every Graph edge. Six packages (53 tools) are on by default; ads and page_admin are opt-in.

• 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 unlocked by an env flag alone.
• Secret hygiene. Value-based redaction of secrets at a single choke-point across logs, errors, tool results, and the write journal.
• Layered architecture. Lint-enforced core ← api ← mcp ← tools ← cli ← server 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. Most of the time goes into 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:

   bash

   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:

   bash

   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

The plugin route has not been walked end-to-end yet. The marketplace reads the plugin from this repository's main branch, and the plugin starts npx -y @ivanbaev/facebook-mcp without a version pin, so it runs whatever release is latest on npm.

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.gitcd facebook-mcpnpm installnpm run buildnode build/index.js setup-token   # with the same FB_* variables as step 3node build/index.js doctor        # pre-flight: token, scopes, package matrixnode 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-mcpclaude 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.
• npx cold start — CI packs each commit, starts it with npx -y from an empty directory on Linux, macOS and Windows, and requires initialize and a non-empty tools/list.

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; in CI it runs only the npx cold-start job (pack, start, initialize and tools/list), which also runs on Linux and Windows. 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.

All three package variables share one namespace of packages and profiles (core, all, reader, publisher, moderator, ads), and a profile name wins over a same-spelled package. That matters most in FB_PACKAGES_DENY: FB_PACKAGES_DENY=core denies the six-package core profile, not the single core package — and the core package is then forced back on anyway, since its identity and rate-limit tools are how you diagnose the surface you just narrowed. A name none of them recognize fails at startup rather than being ignored.

69 tools in 8 packages. 6 packages are on by default; the rest are opt-in via FB_TOOL_PACKAGES. Tier read never mutates. reversible writes are gated by FB_WRITE_MODE; irreversible and spend additionally require a per-call apply plus the plan_id of a preview you just ran, and are never unlocked by an environment variable alone.

How this compares

Point-in-time survey as of 2026-10-29; this market changes monthly, so check the date. Sources and method are in docs/reviews/v3/07-product-manager.md §4; the older long-form write-up (2026-07-21) is docs/analysis/02-market-and-positioning.md. Entries marked unverified were not checked beyond their listing.

If you only need ads, use Meta's official Ads MCP. It is free, needs no developer app of your own, is maintained by the vendor, and covers more ads surface than this project ever will. The ads package here exists for one reason: composing ads with Pages, moderation and messaging under a single token and config, with the same spend gating. That is why it is off by default — ads are not the reason to install this.

If you do not write code, a hosted connector is likely the better fit. The setup here needs a Meta developer app and a token you manage yourself.

The reason to install this is the Pages side, run from your own machine: video and Reels upload from local files, scheduled-post lifecycle, insights that tell you when a metric was renamed or retired, comment and message moderation, and writes you preview before they apply — in a typed, tested, MIT-licensed server under a token you own.

Known limitations

Current, factual, and deliberately unflattering:

• No live Graph API verification. Nothing here has been proven against Meta's servers. Fixtures encode what the API is documented to do; reality gets a vote.
• Published, but brand new. 0.8.0 is on npm with provenance, the .mcpb bundle is attached to the GitHub release and the MCP Registry lists 0.8.0 — but no install path has been walked end-to-end by anyone except CI. See Client compatibility for what that means per client.
• Clients that cannot prompt need an operator token. irreversible and spend writes need a per-call apply plus a plan_id and an out-of-band confirmation the model cannot supply itself. Where the client advertises the MCP elicitation capability, the server asks the human operator through it; where it does not, the caller must pass the FB_CONFIRM_TOKEN value as the tool's confirm_token argument. With neither route, those tools return confirmation_denied.
• Upload progress depends on the client asking for it. Chunked video and Reel uploads emit notifications/progress per chunk — but only when the caller supplies a progressToken on the request, as the MCP spec requires. A client that does not send one gets no frames, and a long upload just looks slow.
• Insights metrics move under you. Meta retired and renamed a large batch of Page/post metrics across three waves (2024-09, 2025-11 and 2026-06-15). The insights tools classify a requested metric and tell you when one is renamed or gone instead of silently returning nothing — but the underlying data loss is Meta's, and no wrapper can undo it.
• Messaging is bound by Meta's 24-hour window. A conversation that has gone quiet for more than 24 hours cannot be replied to without a message tag. This server sends no message tags (the only working one, HUMAN_AGENT, needs its own App Review approval), so such a reply is refused with an explanation.
• Single maintainer, pre-1.0. Tool names, arguments and result shapes are planned to change in 0.9 (see Roadmap). Until 1.0 there is no guaranteed deprecation period.

Not in scope

Two different things: tools that ship but are experimental, and things this server does not do and does not plan to. Listed so you can rule it out in thirty seconds instead of after an install.

Shipped but experimental

These tools are in the tool table and work like the rest, but they are outside the contract the roadmap stabilises: they may change or be removed in any minor release, including after 1.0. Like every other tool, none has been verified against a live Page or ad account.

• Ads writes beyond status and budget (ads package, opt-in): facebook_boost_post, facebook_duplicate_ad_object, facebook_update_ad_set_targeting, facebook_upload_ad_image, facebook_archive_ad_object, facebook_delete_ad_object.
• Messenger labels, reactions and attachments (messages package): facebook_list_labels, facebook_create_label, facebook_assign_label, facebook_delete_label, facebook_react_to_message, facebook_upload_message_attachment.
• Page profile edits (page_admin package, opt-in): facebook_update_page_profile.

The tool descriptions do not carry this marking yet.

Not planned

• Personal profiles and Groups. Publishing to a personal timeline has no API, and the Groups API was discontinued in April 2024. This server operates Pages — nothing else.
• Instagram, Threads, WhatsApp. Different products, different permission sets. Instagram has its own sibling server — see (c) Instagram alongside.
• Webhooks / real-time ingestion. A local stdio server has no public URL to receive callbacks on. Reads are polled, by design.
• A general ad-creation surface. facebook_boost_post is the one create path: one existing Page post, everything PAUSED, a mandatory campaign spend cap, no special ad categories. Ads breadth beyond boosts, paused copies and narrow edits stays with Meta's own tools.
• Events, Live video, organic post targeting, multi-network scheduling. Real needs, outside the Pages publishing, insights, moderation and messaging surface this server is built around.
• Multi-tenant or hosted operation, serving other businesses' Pages or ad accounts. The design targets one operator, Standard Access, own assets, own machine. Anything else needs App Review and Business Verification, which is a different product.
• Telemetry of any kind.

The reasoning is in docs/analysis/01-goals-and-scope.md and, for the current plan, docs/analysis/v3/02-v3-scope.md (that document still uses the old release labels; see Roadmap).

Your responsibilities as the operator

This server automates actions Meta attributes to you, under your app and your token. Automating them does not exempt you from the rules that govern them:

• Meta's Platform Terms and Developer Policies still apply — including the anti-spam and automated-behaviour rules. Bulk or repetitive posting, commenting, or messaging can get a Page restricted or an app disabled, and the fact that a model chose the timing is not a defence.
• Messenger automation must be disclosed. Meta expects users to know when they are talking to an automated system. If you wire the messaging tools to answer people, tell them.
• Content and consent are yours. The tools will publish whatever you point them at; deciding that you have the rights to it — and, for private replies and DMs, that the contact is expected — is not something a wrapper can do.
• Ads are your contract with Meta. Every campaign, ad set or ad this server creates, copies or changes is in your ad account, under the Meta Self-Serve Ad Terms and Advertising Standards you accepted, and you pay for it. Boosts and copies start PAUSED. A boost needs a mandatory spend_cap_minor within FB_ADS_CAMPAIGN_SPEND_CAP_MAX (it is refused while that is unset), and a budget within FB_ADS_BUDGET_CEILING when you set one — but activating a campaign is your decision. facebook_boost_post always declares no special ad category, and it requires special_ad_category: "none" as your attestation of that: never pass it for housing, employment, credit, or social issues, elections or politics. Those ads need a declared category (and, in the EU, are subject to the political-advertising rules) and must be created in Ads Manager. This software is provided under the MIT licence, without warranty; the author is not liable for ad spend or ad content.
• You answer for this server and the model driving it. From 20 November 2026 Meta's Self-Serve Ad Terms make you solely responsible for the acts or omissions of any third-party software you use with the ads APIs — that includes this server and the AI model driving it. Review every plan before you apply it.
• This is not legal advice. It is the honest note that a capable automation tool comes with obligations, and this project would rather say so up front.

The security-side counterpart is in SECURITY.md.

What data the tools read, where it goes (including your AI provider) and what stays on disk is described in the privacy notice.

Roadmap

Work is tracked publicly on the facebook-mcp roadmap board. The plan below is a target, not a promise; the binding version is docs/analysis/v3/04-roadmap-and-risks.md.

The ads and page_admin packages ship in 0.8 already, disabled by default, pre-1.0 and not live-verified; their write tools are mostly experimental.

Older labels. The planning documents written before 2026-10-30 use other numbers for the same releases: their "1.0" is 0.9, their "2.0" is 1.0, and their "3.0" is 2.0. The repository's GitHub milestones still carry the older titles.

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. The exception is moderation, which defaults to apply for its text-free verbs because hiding a comment is high-volume, reversible work — and FB_WRITE_MODE overrides any package default outright, in either direction, so the mode is an operator decision rather than a per-tool promise. What the mode cannot touch: irreversible and spend actions always require an out-of-band confirmation, and anything that reaches a live audience (publishing a post or a Reel, publishing a scheduled post early, sending a DM, or a public comment, reply or comment edit as the Page) additionally requires a plan_id bound to a preview of that exact call. No env flag bypasses either. A session that reads comments or the inbox should run a read-only profile or a client with elicitation — see SECURITY.md.
• 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 original v1.0 release definition, and the parallel task-breakdown. The current plan is in docs/analysis/v3/, and the 2026-10 role reviews are in docs/reviews/v3/.
• Runbooks — operational procedures in docs/runbooks/.
• Error catalog — every Graph error the server classifies, whether it is retried, and what to do: docs/error-catalog.md.
• Documentation site — ivanbbaev.github.io/facebook-mcp.

The environment table, the package/tool tables and the permission tables above, and the error catalog, are generated from the code by npm run metadata; CI fails if they drift.

Support

Best-effort, single-maintainer support runs through GitHub — see SUPPORT.md for how to ask a question, file a bug or a feature request, and report a security issue privately. If you got the server working with a client or a live Page, an issue saying so is useful too: it is how the Client compatibility table turns into ✅.

If the project helps you, you can sponsor it through GitHub Sponsors (other channels are listed in .github/FUNDING.yml). Sponsoring buys no priority support and no SLA.

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