facebook-mcp

Facebook automation exposed as an MCP (Model Context Protocol) server.

Capabilities:

• get_user_latest_post_time — a user's latest post publish time (e.g. exampleuser)

• get_user_recent_posts — recent posts with text, time and permalink

• search_people — keyword search for people (/search/people?q=...)

• search_pages — keyword search for pages (/search/pages?q=...)

• send_message — send a Messenger message

Design docs: ARCHITECTURE.en.md (English) · ARCHITECTURE.md (中文).

Status

• M0 scaffolding — done

• M1 transport (curl_cffi + proxy + retry/throttle) — done

• M2 session + routes + profile client + get_user_latest_post_time — done, verified live

• M3 search (search_people / search_pages) — done, verified live over pure HTTP

• M4 CDP transport (cookie bootstrap + packet capture) — done

• M5 send_message — done, verified live (browser path)

All five tools work against the live site.

How send_message works

Messages travel over wss://gateway.facebook.com/ws/lightspeed (JSON tasks in a 16-byte binary frame) — not over HTTP and not via a service worker. Connect with the account's cookies, send task 46, and the server answers replaceOptimsiticMessage with a real message_id.

A Couldn't send verdict is ambiguous: the recipient may have messaging turned off (common for pages), the thread type may need the DOM path, or the thread may need extra context. The client reports it as-is; auto mode then tries the UI once to tell those apart, since the server has already stated nothing was sent.

FB_MESSAGE_TRANSPORT=lightspeed   # protocol only (no browser, no fallback)
FB_MESSAGE_TRANSPORT=auto         # protocol first, UI fallback (default)
FB_MESSAGE_TRANSPORT=ui           # legacy CDP-driven DOM path

The UI path remains as a fallback (and is the only way to start a conversation), but sending no longer needs a browser. See ARCHITECTURE.en.md §8.3 for the frame layout and what the gateway's verdict does and does not prove.

Related MCP server: Facebook MCP Server

Install

/opt/homebrew/bin/python3.11 -m venv .venv
.venv/bin/pip install -e ".[dev]"

Requires mcp>=1.2,<2 (official MCP Python SDK, mcp.server.fastmcp).

⚠️ This project intentionally pins mcp<2.

Configure

cp .env.example .env
# fill in FB_COOKIE / FB_COOKIE_FILE for authenticated operations

A proxy is often required to reach Facebook. The transport resolves it automatically: FB_PROXY → HTTPS_PROXY env → macOS system proxy.

Tools

Credentials: ~/.facebook-mcp/

Cookies live outside the repository, one directory per Facebook account:

~/.facebook-mcp/                      # 0700
└── accounts/
    └── default/                      # 0700
        ├── cookies.txt               # 0600, Netscape format
        └── account.json              # 0600, metadata + per-account overrides

Which tools need credentials — measured in an incognito Chrome with zero Facebook cookies (ARCHITECTURE.en.md §8.1):

Populate an account

# A. Export from a logged-in Chrome (one time)
bash tools/launch_chrome_debug.sh
.venv/bin/python tools/export_cookies.py --account default

# B. Or decrypt straight from your Chrome profile
.venv/bin/python tools/import_cookies.py --account default

# Inspect
.venv/bin/python tools/export_cookies.py --list

Then run without a browser:

FB_TRANSPORT_MODE=http .venv/bin/facebook-mcp     # uses accounts/default

Or let the server borrow your live Chrome once: cookies are bootstrapped on the first authenticated call and written into the account store, so later runs are pure HTTP.

FB_TRANSPORT_MODE=auto .venv/bin/facebook-mcp

Search never goes through the browser once cookies exist: require_auth() ensures a jar, and the request then goes over curl_cffi. Clients set no transport hint at all — the browser is reached only through cdp_from().

Multiple accounts

Per process (fully isolated, recommended):

{
  "mcpServers": {
    "facebook-default": {
      "command": ".../.venv/bin/facebook-mcp",
      "env": { "FB_ACCOUNT": "default", "FB_TRANSPORT_MODE": "http" }
    },
    "facebook-work": {
      "command": ".../.venv/bin/facebook-mcp",
      "env": { "FB_ACCOUNT": "work", "FB_TRANSPORT_MODE": "http" }
    }
  }
}

Per call — every tool takes an optional account argument:

search_pages(q="pest control", account="work")
send_message(recipient="exampleuser", text="hi", account="work")

Each account can bind its own browser via cdp_url in its account.json (e.g. {"cdp_url": "http://127.0.0.1:9223"}), so two accounts never fight over the same Chrome tab. The same file holds that account's live GraphQL doc_ids under "doc_ids", so a Facebook build change is picked up per account without editing the repository.

Maintenance: Facebook ships a new frontend build

GraphQL doc_ids and variables templates change. Re-capture them:

.venv/bin/python tools/sniff.py --navigate "https://www.facebook.com/search/pages?q=pest%20control" \
                               --seconds 20 --save-templates

--save-templates records the fresh doc_ids in ~/.facebook-mcp/accounts/<name>/account.json and promotes the search variables template into the package when its shape changed.

• doc_id rotation only → no source change, no commit: the registry value in routes/graphql.py is just the bootstrap default used before the first capture.

• variables shape changed → the promoted template is a tracked file (src/facebook_mcp/routes/templates/search_results.json), so that case does produce a diff and belongs in a commit.

The override is read when the server starts, so restart the MCP server to pick up a refreshed doc_id.

Helpers

Development

make install     # .venv (Python 3.11) + dev dependencies
make hooks       # commit-msg hook + commit template
make check       # main local checks: lint, format, layers, docs, tests, smoke

CI (.github/workflows/ci.yml)

Tests are fully offline — a local http.server and a mock DevTools (WebSocket) server stand in for Facebook and Chrome, so CI needs no network or credentials.

Verify against the live site

.venv/bin/python tools/probe.py profile exampleuser
.venv/bin/python tools/probe.py search pages "pest control"

Run

.venv/bin/facebook-mcp            # stdio transport (default)
# or
.venv/bin/python -m facebook_mcp

HTTP transports are available too (the SDK supports them):

# streamable-http on 127.0.0.1:8000/mcp
.venv/bin/python -c "from facebook_mcp.server import mcp; mcp.run('streamable-http')"

MCP client config (example)

{
  "mcpServers": {
    "facebook": {
      "command": "/Users/jin/Documents/GitHub/facebook-mcp/.venv/bin/facebook-mcp",
      "env": { "FB_COOKIE_FILE": "/path/to/cookies.txt" }
    }
  }
}

Commit convention

Conventional Commits, enforced locally by make hooks and in CI by tools/commit_msg.py:

feat(search): paginate results with page_info.end_cursor
fix(accounts): keep cookies out of the repository
docs: explain why send_message needs a browser

Types: feat fix docs test refactor perf build ci chore revert. Scopes: core transport session routes clients services server accounts cdp http proxy profile post search message tools tests ci docs deps release. Subject: imperative, lowercase, no trailing period, header ≤ 72 chars.

See CONTRIBUTING.md for the full rules and examples.

Pushing over SSH? Use a repo-scoped deploy key (~/.ssh/github-action-key-*, 0600, never committed, one repo per key). CI needs none: actions/checkout uses the built-in GITHUB_TOKEN.

License

MIT © facebook-mcp contributors

Not affiliated with, endorsed by, or supported by Meta/Facebook. Use it only with accounts you own or are authorized to automate, and respect Facebook's terms of service and local anti-spam / privacy law.

All usernames, page names and ids in this repository are placeholders (exampleuser, 100000000000001, …). See CONTRIBUTING.md → Documentation privacy.