Skip to main content
Glama
facebook-lyr

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).

  • Page index — every active doc and the question it owns.

Related MCP server: FBEM

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

Tool

What it gives you

get_me / get_account_status

Authenticated identity + session validity

get_user_posts / get_page_posts

Recent timeline posts for a user or Page

get_page_info / get_profile-style info

Profile / Page summary (bio, follower counts)

get_post_details / get_post_comments

Single post + its comments

search_posts / search_people / search_pages / search_groups

Keyword discovery across Facebook

get_group / get_group_posts / get_group_members

Group metadata, feed, and member list

get_conversations / get_conversation_messages

Messenger inbox + thread bodies

get_notifications

New alerts (messages, tags, follows, page activity)

get_events

Upcoming events for the identity

get_account_posting_status

Posting limits + attempt history for an identity

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.

Tool

Notes

create_post

Text post (≤ 5000 chars)

create_photo_post

Image (file/URL), normalized to feed spec

create_video_post

Video (file/URL) — best-effort

create_carousel_post

2–10 image carousel

delete_post

Delete one of your own posts (delete.php)

save_post / unsave_post

Bookmark / un-bookmark a post

comment_on_post

Comment on a post

send_message / delete_message

Send, or delete/unsend, a Messenger message

send_typing_indicator / mark_conversation_seen

Presence writes (no quota)

Accounts & identity

Tool

What it gives you

list_accounts / get_active_account_info

Stored identities + which is active

list_switchable_accounts

Every Page/profile the session can switch to

add_account / remove_account / update_account_cookies

Manage per-identity cookie stores

import_account_from_browser

Import an identity's cookies from a browser

switch_active_account / set_active_page

Change the identity every tool acts as

close_session

Release active clients

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 a write path is dead, the tool fails loudly and honestly instead of faking success:

Capability

Status

Timeline publishing (text/photo/video/carousel) via Graph API

🟢 working — requires a page-scoped token (see below); the cookie path is decommissioned

Comment on posts / delete own posts

🟢 working (Graph API for comments, cookie delete.php for delete)

Save / unsave posts, notifications, events, group members

🟢 working (legacy endpoints still alive)

Messenger text send / delete / typing / seen

🔴 decommissioned — send_messages.php returns 404 (verified live); the read side (get_conversations) still works

React to post/comment, edit post, follow, friend requests, Messenger media/reactions

🔴 endpoint removed (404) — not possible with cookies or the current token

Post via cookies for migrated accounts

🔴 returns a clear "official API required" error

Graph API writes need a page-scoped access token, deployed as a sidecar ~/.facebook-lyr/.env:

FACEBOOK_GRAPH_API_TOKEN=...
FACEBOOK_GRAPH_API_PAGE_ID=...

When the token is present, facebook-lyr automatically routes timeline publishing + comments through the Graph API; without it, those writes fail honestly with the "official API required" error. Read tools and the messenger read side are unaffected.

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.


☕ Support & Sponsorship

If you find this project useful, consider supporting ongoing development:

Sponsor Donate

Your support funds new features, releases, and infrastructure for the whole ecosystem.

Updating

Use facebook-lyr update --check to check without changing the installation, or facebook-lyr update to update it. facebook-lyr upgrade is an alias. The command delegates to the manager that owns this installation (uv, pipx, or pip) and refuses editable, local-checkout, system, or unknown installs instead of replacing package-manager-owned files. For example: uv tool upgrade facebook-lyr.

Available Tools

41 tools
add_accountAdd Facebook AccountA
Destructive

Store a new Facebook identity's cookie set for agent use.

The cookies dict must contain at least c_user and xs (a logged-in facebook.com session). After adding, all tools act as this identity when set_as_active is True (default).

Inputs: name (required), cookies (required), account_id (required), username, +2 more. Returns: object

close_sessionClose SessionA
Destructive

Close all active API clients and clean up resources.

Inputs: no named parameters. Returns: object

comment_on_postComment On PostA
Destructive

Comment on a post as the active (or specified) Facebook identity.

Validates the text, checks the identity's posting limits, records the attempt, and comments through the web composer. Fails honestly if cookie-based commenting is decommissioned for the account.

Inputs: text (required), post_id (required), confirm, account_id. Returns: object

create_carousel_postCreate Carousel PostA
Destructive

Upload multiple photos and publish them as one carousel post.

Each image is validated and normalized before the upload attempt. Best-effort: modern Facebook may reject cookie-based carousels; failures surface as clear, honest errors.

Inputs: sources (required), confirm, message, account_id. Returns: object

create_photo_postCreate Photo PostA
Destructive

Upload a photo and publish it as the active (or specified) identity.

The image is validated and normalized (resized to Facebook's feed spec) before the upload attempt. Best-effort: modern Facebook may reject cookie-based uploads; failures surface as clear errors.

Inputs: source (required), confirm, message, account_id. Returns: object

create_postCreate PostA
Destructive

Publish a text post as the active (or specified) Facebook identity.

Validates the text, checks the identity's posting limits, and publishes through the web composer. If Facebook has decommissioned cookie-based writing for the account, returns a clear error rather than a false success.

Inputs: status (required), confirm, account_id. Returns: object

create_video_postCreate Video PostA
Destructive

Upload a video and publish it as the active (or specified) identity.

The video file is validated before the upload attempt. Best-effort: modern Facebook has largely decommissioned cookie-based video uploads; failures surface as clear, honest errors.

Inputs: source (required), confirm, message, account_id. Returns: object

delete_messageDelete MessageA
Destructive

Delete (unsend) a Messenger message as the active (or specified) identity.

Validates the ids, checks the identity's posting limits, records the attempt, and deletes via the legacy Mercury endpoint. Fails honestly if deletion is decommissioned for the account.

Inputs: thread_id (required), message_id (required), confirm, account_id. Returns: object

delete_postDelete PostA
Destructive

Delete one of the active (or specified) identity's own posts.

Checks the identity's posting limits, records the attempt, and deletes through the delete.php confirm flow. Fails honestly if the post is not available (already deleted) or deletion is decommissioned.

Inputs: post_id (required), confirm, account_id. Returns: object

get_account_posting_statusGet Account Posting StatusB
Read-only

Check a stored identity's posting limits and history.

Inputs: account_id. Returns: object

get_account_statusGet Account StatusA
Read-only

Check the current cookie-session status and active Page.

Returns: Dict with valid (bool), cookie_source, me (id/name), and active_page_id / active_page_name.

Inputs: no named parameters. Returns: object

get_active_account_infoGet Active AccountA
Read-only

Get information about the currently active Facebook identity.

Returns: Active account metadata or a message when none is set.

Inputs: no named parameters. Returns: object

get_conversation_messagesGet Conversation MessagesA
Read-only

Read messages from a Messenger conversation.

Inputs: thread_id (required). Returns: object

get_conversationsGet ConversationsA
Read-only

List Messenger conversations for the authenticated account.

Inputs: limit. Returns: object

get_eventsGet EventsA
Read-only

List upcoming events relevant to the authenticated identity.

Returns embedded event rows (id, name, start_date_time, url) from the events hub. Event details that load client-side are not available via cookie scraping.

Inputs: limit. Returns: object

get_groupGet GroupA
Read-only

Get Facebook group details.

Inputs: group_id (required). Returns: object

get_group_membersGet Group MembersA
Read-only

List members of a Facebook group.

Best-effort: served from the legacy browser-list endpoint, which may return an error for private groups or migrated surfaces — the result then explains the limitation honestly.

Inputs: group_id (required), limit. Returns: object

get_group_postsGet Group PostsA
Read-only

Get recent posts from a group feed.

Inputs: group_id (required), max_posts. Returns: object

get_meGet MeA
Read-only

Get the identity of the authenticated Facebook user.

Resolved from the imported browser-cookie session (c_user / xs). Useful to confirm whose session is configured and whether it is still valid.

Returns: Dict with the user's id, name, and username.

Inputs: no named parameters. Returns: object

get_notificationsGet NotificationsA
Read-only

List the authenticated identity's recent Facebook notifications.

Includes message alerts, tags, follows, and page activity. Useful for an agent to know what needs attention before deciding to act.

Inputs: limit. Returns: object

get_page_infoGet Page InfoA
Read-only

Get Facebook Page/profile details by username.

Fetches the public (or logged-in) profile page and parses name, id, bio, and follower counts from the embedded page data.

Inputs: username (required). Returns: object

get_page_postsGet Page PostsA
Read-only

Get recent posts from a Facebook Page's timeline.

Inputs: username (required), max_posts. Returns: object

get_post_commentsGet Post CommentsC
Read-only

Fetch comments on a post.

Inputs: post_id (required), limit. Returns: object

get_post_detailsGet Post DetailsA
Read-only

Get details for a single post by its URL.

Inputs: post_url (required). Returns: object

get_user_postsGet User PostsA
Read-only

Get recent posts from a user's or Page's timeline.

Inputs: username (required), max_posts. Returns: object

import_account_from_browserImport Account from BrowserA
Destructive

Import a Facebook identity's cookies directly from a browser.

Uses the native cookie import machinery (the same as --login). The browser must be logged into that identity. Example: a Page whose session is open in your browser profile.

Inputs: name (required), account_id (required), browser, username, +2 more. Returns: object

list_accountsList Facebook AccountsA
Read-only

List all stored Facebook identities (cookie sets).

Each stored identity has its own cookies (c_user/xs); the active one is what every tool acts as. Use switch_active_account to change it.

Returns: Dict with accounts (id, name, username, identity_type, is_active, last_used), total_accounts, and active_account.

Inputs: no named parameters. Returns: object

list_switchable_accountsList Switchable AccountsA
Read-only

Discover every identity the logged-in session can switch to.

Reads Facebook's account switcher — the Pages you administer, linked profiles, and the user profile itself. This is the discovery source an agent uses to learn which identities exist for this session.

Returns: Dict with accounts (id, name, typename, is_current) and total.

Inputs: no named parameters. Returns: object

mark_conversation_seenMark Conversation SeenA

Mark a Messenger conversation as seen (clears the unread badge).

Inputs: thread_id (required). Returns: object

remove_accountRemove Facebook AccountA
Destructive

Remove a stored Facebook identity's cookie set.

Inputs: account_id (required). Returns: object

save_postSave PostA
Idempotent

Save/bookmark a post to the active (or specified) identity's Saved.

Best-effort: the legacy save endpoint submits the mutation but cannot always confirm it synchronously — the result tells you to verify in the Saved collection.

Inputs: post_id (required), confirm, account_id. Returns: object

search_groupsSearch GroupsB
Read-only

Search for Facebook groups by name.

Inputs: query (required), limit. Returns: object

search_pagesSearch PagesA
Read-only

Search for public Facebook Pages by name.

Inputs: query (required), limit. Returns: object

search_peopleSearch PeopleA
Read-only

Search for people by name.

Useful to find a person before messaging them (pair with get_conversations / send_message).

Inputs: query (required), limit. Returns: object

search_postsSearch PostsA
Read-only

Search public posts by keyword.

Inputs: query (required), limit. Returns: object

send_messageSend MessageA
Destructive

Send a Messenger text message as the active (or specified) identity.

Validates the text, checks the identity's posting limits, records the attempt, and sends via the legacy Mercury endpoint. Fails honestly if sending is decommissioned for the account.

Inputs: message (required), thread_id (required), confirm, account_id. Returns: object

send_typing_indicatorSend Typing IndicatorB

Send a typing indicator to a conversation (typing_on / typing_off).

Inputs: thread_id (required), typing. Returns: object

set_active_pageSet Active PageA
Destructive

Persist the active Facebook Page for display/context purposes.

Note: cookie scraping operates as the account whose cookies are imported (c_user). This tool records a Page for agent bookkeeping and for Page-mode sessions (m_page_voice cookie present). It does not switch the acting identity on its own.

Inputs: page_id (required), page_name. Returns: object

switch_active_accountSwitch Active AccountA

Switch which stored identity all tools act as.

Subsequent tool calls load the selected identity's cookie set, so reads and writes happen as that identity.

Inputs: account_id (required). Returns: object

unsave_postUnsave PostA
DestructiveIdempotent

Remove a post from the active (or specified) identity's Saved.

Best-effort: the legacy save endpoint submits the mutation but cannot always confirm it synchronously — the result tells you to verify in the Saved collection.

Inputs: post_id (required), confirm, account_id. Returns: object

update_account_cookiesUpdate Account CookiesA
Destructive

Update cookies for an existing stored Facebook identity.

Useful for refreshing an expired session without re-adding the account.

Inputs: cookies (required), account_id (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 41 tools

    Disambiguation4/5

    Most tools target distinct resources and actions (e.g., get_page_posts vs. get_user_posts vs. get_group_posts, create_post vs. create_photo_post). A few overlaps exist, such as get_me, get_account_status, and get_active_account_info, but their descriptions clarify the intent.

    Naming Consistency4/5

    The majority follow a verb_noun pattern (get_*, create_*, delete_*, search_*, list_*, switch_*, set_*, add_*, remove_*). Minor deviations like get_me, comment_on_post, and send_typing_indicator are acceptable but prevent a perfect score.

    Tool Count2/5

    At 41 tools, the count exceeds the 'too many' threshold of 25+. While the server covers a broad Facebook surface, many tools could be consolidated (e.g., generic post retrieval per resource type) without losing capability.

    Completeness4/5

    The tool surface covers account management, posts, comments, pages, groups, search, and Messenger with create/read/delete operations. Minor gaps exist, such as no update_post, no delete_comment, and no group creation, but core workflows are well supported.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      A Model Context Protocol (MCP) server implementation that provides Facebook Page interaction and management capabilities. This server enables automated posting, comment moderation, and content retrieval.
      7
      77
      -
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that enables AI agents to post Reels and Photos to Facebook by capturing and replaying the native web API through a Chrome extension.
      6
      13
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server that wraps Meta's Messenger Platform, Instagram Messaging, and comment moderation APIs as semantic tools for LLM agents to read inbox, reply, and moderate comments.
      16
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server for Facebook Pages organic analytics and management using Meta Graph API v25.0. Enables AI assistants to read page insights, posts, comments, and publish content via natural language.
      9
      61 npm
      MIT

    Appeared in Searches