facebook-lyr

What it does

• Read & discover — profiles, Pages, timeline posts, post details & comments, groups (+ members), people/page/group/post search, Messenger conversations & messages, notifications, and upcoming events.

• Write & engage — text / photo / video / carousel posts, delete your own posts, save & unsave posts, comment on posts, and full Messenger operations (send, delete/unsend, typing indicator, mark-seen).

• Multi-account — store multiple identities (your user, Pages you administer, linked profiles), each with its own cookie set; switch the active identity any time, discover switchable accounts, import cookies per identity, and enforce per-identity posting limits + cooldowns + attempt history.

• Agent-first CLI — AXI-compliant, TOON output, session hooks for Claude Code / Codex, and a self-installing agent skill.

Modeled directly on instagram-lyr — the same architecture, CLI conventions, and browser-cookie authentication flow. Threads lives in a separate project (threads-lyr).

Related MCP server: FBEM

Why cookie scraping?

The official Graph API requires a Meta developer app, app review, and page-scoped tokens — and it cannot see anything your app wasn't granted. Cookie scraping reuses the exact session your browser has, so the agent reads and acts on Facebook the way you would: full timelines, groups, Messenger inboxes, notifications, and events.

• curl_cffi with Chrome TLS impersonation defeats JA3 fingerprint detection.

• The fb_dtsg CSRF token is extracted from the logged-in homepage and auto-refreshed on rotation.

• Messenger uses the legacy Mercury ajax endpoints (threadlist_info.php, thread_info.php, send_messages.php, delete_messages.php) where they still exist.

• Feeds, profiles, notifications, events, and search are parsed from Facebook's embedded JSON with a resilient recursive deep-scan — no fragile selectors.

• Account discovery reads the relay data on /accounts/ to list every Page / profile the session can switch to.

Quick install

One-line installation (clones to ~/projects/facebook-lyr):

curl -fsSL https://raw.githubusercontent.com/ishan-parihar/facebook-lyr/main/install.sh | bash

Or install from PyPI with uv (no clone):

uv tool install facebook-lyr

Or in any MCP client — just point it at the package:

{
  "mcpServers": {
    "facebook": {
      "command": "uvx",
      "args": ["facebook-lyr"]
    }
  }
}

Quick start

uv sync                        # install dependencies (repo install)
facebook-lyr --login           # import cookies from your browser (Brave, Chrome, Edge, Firefox, Zen, ...)
facebook-lyr --status          # "status: valid" when the session works
facebook-lyr                   # start the MCP server (stdio)

Headless agents (no interactive step): export the session directly —

export FACEBOOK_COOKIES='{"c_user":"12345","xs":"abc...","fr":"...","datr":"..."}'
facebook-lyr --status

Cookies are stored at ~/.facebook-lyr/profile/cookies.json (mode 0600) and never leave your machine.

Tool surface (41 tools)

Read & discover

Write & engage

Every write tool is confirm-gated (confirm=true), respects the identity's daily cap + cooldown, and records the attempt in the identity's posting history.

Accounts & identity

Authentication

• Interactive: facebook-lyr --login — imports c_user, xs, fr, datr, … from your browser's cookie store (Brave, Chrome, Edge, Firefox, Zen, Chromium, Opera, Arc, Vivaldi, LibreWolf, Waterfox, Floorp, and more).

• Headless: FACEBOOK_COOKIES env var (JSON object with at least c_user and xs).

• If the session expires (login wall / 403), tools auto-trigger re-login and tell you to run --login.

Multi-account (users + Pages)

Store multiple identities — your user account, Pages you administer, linked profiles — each with its own cookie set under ~/.facebook-lyr/accounts/<id>/:

facebook-lyr import_account_from_browser --account_id 100064606727322 --name "My Page" --browser zen
facebook-lyr switch_active_account --account_id 100064606727322
facebook-lyr get_active_account_info

Cookie rotations (xs/fr refreshes) are written back to the owning identity's store automatically, so stored jars stay in sync with the live session. Posting limits, cooldowns, and attempt history are tracked per identity.

Honest limitations

Facebook has been decommissioning its cookie-era write endpoints. Where an endpoint is dead, the tool fails loudly and honestly instead of faking success:

Read tools are unaffected. For the decommissioned cluster, the official Graph API (Page/App tokens) is the required path — the same constraint that killed cookie-based posting libraries.

CLI reference

facebook-lyr --help                 # usage
facebook-lyr --list-tools           # all 41 tools
facebook-lyr --tool-info <tool>     # params for one tool
facebook-lyr <tool> --param value   # call a tool directly (TOON output)
facebook-lyr --login | --status | --logout
facebook-lyr --install-hook         # session hooks for Claude Code / Codex
facebook-lyr --install-skill        # agent skill for auto-discovery

Development

uv sync --extra dev
uv run pytest        # 259 tests: parsers, write surface, limits, Tier-1 tools
uv run ruff check .

License

MIT — see LICENSE.