facebook-mcp

An open-source Model Context Protocol server that lets AI assistants manage your Facebook Pages: publish and schedule posts, moderate comments, and read analytics. It's built on FastMCP and works with Claude Desktop, Claude Code, ChatGPT, Gemini CLI, Cursor, VS Code and any other MCP client.

"Schedule tomorrow's 9am post on Acme Coffee announcing the new menu, then hide any spam comments on yesterday's post."

Features

• Multi-page: give it one user token and it finds every Page you manage. Each Page uses its own Page token automatically.
• 16 tools covering posts, scheduling, photos, Reels, comments, moderation and insights.
• Safe by default: tools are labelled read-only or destructive (MCP annotations), a --read-only mode hides write tools, requests are signed with appsecret_proof, and tokens never appear in URLs or logs.
• Runs anywhere: stdio for desktop clients, streamable HTTP (with optional bearer auth) for remote clients, or the Docker image.
• Production-quality code: typed (mypy --strict), layered architecture, and over 95% test coverage against a mocked Graph API.

Quick start

1. Get a token. Create a Meta app and generate an access token with the Page permissions listed in docs/setup-meta-app.md. This takes about 5 minutes.

2. Add the server to your MCP client. You'll need uv. For example, in Claude Desktop's claude_desktop_config.json:

{
  "mcpServers": {
    "facebook": {
      "command": "uvx",
      "args": ["facebook-mcp"],
      "env": {
        "FB_USER_ACCESS_TOKEN": "your-long-lived-user-token",
        "FB_APP_SECRET": "your-app-secret"
      }
    }
  }
}

Config for every other client (Claude Code, ChatGPT, Gemini CLI, Cursor, VS Code, Docker) is in docs/clients.md.

3. Ask your assistant something like "Which Facebook Pages can you manage?"

Tools

Every tool except list_pages accepts an optional page (a Page id or exact name). Leave it out and the server uses the default Page. For post ids, it uses the Page that owns the post.

Configuration

Settings come from environment variables, or from a .env file in the working directory (see .env.example).

CLI flags override environment variables:

facebook-mcp --transport http --port 8000 --read-only
facebook-mcp exchange-token --app-id 123 --token SHORT_LIVED_TOKEN   # reads FB_APP_SECRET

Security

• Use --read-only until you trust your setup.
• Always set MCP_AUTH_TOKEN when serving over HTTP, and never expose an unauthenticated server to the internet.
• Turn on Require App Secret in your Meta app's advanced settings, so a leaked token can't be used without your app secret.
• Never commit tokens. .env is git-ignored.

To report a vulnerability, see SECURITY.md.

Documentation

• Setting up a Meta app and tokens
• Connecting MCP clients
• Architecture and design

Contributing

Contributions are welcome. See CONTRIBUTING.md for the dev setup and guidelines. In short: uv sync, then uv run pytest.

License

MIT © Salinda Hulangamuwa

This is an independent project. It is not affiliated with, endorsed by, or sponsored by Meta Platforms, Inc. Facebook is a trademark of Meta Platforms, Inc.