facebook-lyr
A Facebook/Messenger MCP server that lets AI agents read and act on Facebook using an imported browser-cookie session (no Graph API app or tokens).
Identity & accounts — confirm who you're logged in as, check session validity, list stored identities, discover switchable Pages/profiles, add/remove/update accounts, import cookies from a browser, and switch the active identity or Page.
Read profiles & Pages — fetch Page/profile info (name, bio, follower counts) and recent timeline posts.
Read & search posts — get post details, comments, and recent user/Page feed posts; search public posts, people, Pages, and groups by keyword.
Groups — fetch group metadata, group feed posts, and member lists; search for groups.
Messenger (read) — list conversations and read messages in a thread.
Notifications & events — list recent notifications (messages, tags, follows, page activity) and upcoming events.
Publish & engage (writes) — create text, photo, video, and carousel posts; delete your own posts; save/unsave posts; and comment on posts (all confirm-gated and rate-limited per identity).
Messenger (write) — send and delete/unsend messages, mark conversations seen, and send typing indicators.
Posting governance — check an identity's daily posting limits, cooldowns, and attempt history.
Session management — close active clients and clean up resources.
Provides tools for interacting with Facebook and Messenger through the authenticated browser session, enabling profile and page reads, post and comment search, groups, Messenger conversations, notifications, events, and multi-account + Page switching. Supports writing operations like creating posts, commenting, sending/deleting Messenger messages, and managing posting limits per identity.
This server is modeled directly on the instagram-lyr architecture and conventions, sharing the same browser-cookie authentication flow, but Instagram itself is not a target of this Facebook-specific MCP server.
Provides tools for full Messenger operations through the authenticated session, including sending and deleting/unsending messages, typing indicators, and marking conversations as seen, using the legacy Mercury ajax endpoints.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@facebook-lyr Show me my most recent Facebook messages from Messenger"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
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_cffiwith Chrome TLS impersonation defeats JA3 fingerprint detection.The
fb_dtsgCSRF 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 | bashOr install from PyPI with uv (no clone):
uv tool install facebook-lyrOr 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 --statusCookies are stored at
~/.facebook-lyr/profile/cookies.json(mode0600) and never leave your machine.
Tool surface (41 tools)
Read & discover
Tool | What it gives you |
| Authenticated identity + session validity |
| Recent timeline posts for a user or Page |
| Profile / Page summary (bio, follower counts) |
| Single post + its comments |
| Keyword discovery across Facebook |
| Group metadata, feed, and member list |
| Messenger inbox + thread bodies |
| New alerts (messages, tags, follows, page activity) |
| Upcoming events for the identity |
| 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 |
| Text post (≤ 5000 chars) |
| Image (file/URL), normalized to feed spec |
| Video (file/URL) — best-effort |
| 2–10 image carousel |
| Delete one of your own posts ( |
| Bookmark / un-bookmark a post |
| Comment on a post |
| Send, or delete/unsend, a Messenger message |
| Presence writes (no quota) |
Accounts & identity
Tool | What it gives you |
| Stored identities + which is active |
| Every Page/profile the session can switch to |
| Manage per-identity cookie stores |
| Import an identity's cookies from a browser |
| Change the identity every tool acts as |
| Release active clients |
Authentication
Interactive:
facebook-lyr --login— importsc_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_COOKIESenv var (JSON object with at leastc_userandxs).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_infoCookie 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 |
Save / unsave posts, notifications, events, group members | 🟢 working (legacy endpoints still alive) |
Messenger text send / delete / typing / seen | 🔴 decommissioned — |
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-discoveryDevelopment
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:
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 toolsadd_accountAdd Facebook AccountADestructive
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 SessionADestructive
Close all active API clients and clean up resources.
Inputs: no named parameters. Returns: object
comment_on_postComment On PostADestructive
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 PostADestructive
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 PostADestructive
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 PostADestructive
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 PostADestructive
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 MessageADestructive
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 PostADestructive
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 StatusBRead-only
Check a stored identity's posting limits and history.
Inputs: account_id. Returns: object
get_account_statusGet Account StatusARead-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 AccountARead-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 MessagesARead-only
Read messages from a Messenger conversation.
Inputs: thread_id (required). Returns: object
get_conversationsGet ConversationsARead-only
List Messenger conversations for the authenticated account.
Inputs: limit. Returns: object
get_eventsGet EventsARead-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 GroupARead-only
Get Facebook group details.
Inputs: group_id (required). Returns: object
get_group_membersGet Group MembersARead-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 PostsARead-only
Get recent posts from a group feed.
Inputs: group_id (required), max_posts. Returns: object
get_meGet MeARead-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 NotificationsARead-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 InfoARead-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 PostsARead-only
Get recent posts from a Facebook Page's timeline.
Inputs: username (required), max_posts. Returns: object
get_post_commentsGet Post CommentsCRead-only
Fetch comments on a post.
Inputs: post_id (required), limit. Returns: object
get_post_detailsGet Post DetailsARead-only
Get details for a single post by its URL.
Inputs: post_url (required). Returns: object
get_user_postsGet User PostsARead-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 BrowserADestructive
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 AccountsARead-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 AccountsARead-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 AccountADestructive
Remove a stored Facebook identity's cookie set.
Inputs: account_id (required). Returns: object
save_postSave PostAIdempotent
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 GroupsBRead-only
Search for Facebook groups by name.
Inputs: query (required), limit. Returns: object
search_pagesSearch PagesARead-only
Search for public Facebook Pages by name.
Inputs: query (required), limit. Returns: object
search_peopleSearch PeopleARead-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 PostsARead-only
Search public posts by keyword.
Inputs: query (required), limit. Returns: object
send_messageSend MessageADestructive
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 PageADestructive
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 PostADestructiveIdempotent
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 CookiesADestructive
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
Scored across 41 tools
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.
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.
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.
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
Related MCP Connectors
Managed LinkedIn MCP server for AI agents: search, connect, message and enrich on accounts you own.
Meta Ads MCP server: run Facebook and Instagram campaigns, ad sets, ads and reports from AI.
Hosted Meta Ads MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Social media MCP server: your Instagram, TikTok, YouTube, LinkedIn and Threads history for your AI.
Related MCP Servers
- FlicenseAqualityDmaintenanceA Model Context Protocol (MCP) server implementation that provides Facebook Page interaction and management capabilities. This server enables automated posting, comment moderation, and content retrieval.777-
- AlicenseAqualityDmaintenanceAn 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.613MIT
- AlicenseAqualityDmaintenanceMCP 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.16MIT
- AlicenseAqualityDmaintenanceMCP 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.961 npmMIT