Messenger Local MCP
Provides tools for accessing allowed Messenger conversations through a self-hosted mautrix-meta/Matrix bridge, including listing chats, fetching recent messages, searching a local index, refreshing history, and optionally sending text with durable request IDs and send-status checks.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Messenger Local MCP
Local Messenger tools for Codex, Claude Code and Claude Desktop, through a self-hosted mautrix-meta / Matrix bridge.
Read only allowed conversations, search a local index, and optionally send text on the user's request. No password or cookie is exposed as an MCP tool.
Unofficial integration: Meta may disconnect, challenge or restrict your account. Read SECURITY.md before connecting an account you depend on.
Features
Fresh messages on demand; cache results are explicitly marked when refresh fails.
Exact chat names or Matrix room IDs, Unicode case-insensitive search, timestamp filters and pagination.
Local allowlist: AI tools cannot add contacts or enable sending.
Durable send ledger shared across clients, with stable request IDs to prevent duplicate Matrix submissions.
Separate accepted-by-Matrix and bridged status; neither proves the recipient read a message.
Stdio transport, no public MCP port and no automatic Facebook login.
Media uploads, reactions and calls are not MCP features. History is partial: only fetched events are indexed, and edits/deletions outside the fetched window may remain stale. Deleting an edit itself is not fully reconstructed.
Related MCP server: whatsapp-mcp
Install
Requires Python 3.11+, Docker Compose with Linux containers for the included stack, and a Facebook account. Docker Desktop must be running.
From this checkout in PowerShell:
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\python.exe -m messenger_mcp init
.\.venv\Scripts\python.exe setup_stack.py prepare
.\.venv\Scripts\python.exe setup_stack.py startOn Linux/macOS use .venv/bin/python. Existing configuration is never overwritten. The bridge example is generated by its pinned Docker image; no upstream source is bundled.
Create a local Matrix account with a password different from Facebook:
docker compose exec synapse register_new_matrix_user -u owner --no-admin -c /data/homeserver.yaml http://localhost:8008
.\.venv\Scripts\python.exe -m messenger_mcp login
.\.venv\Scripts\python.exe -m messenger_mcp bridge-loginIn the bridge console enter /restart and follow the prompts. Credentials belong only in your local console, never in an AI chat or issue. /quit exits without disconnecting the bridge. If Meta flags the account, stop the bridge and complete verification in the official app; do not loop login attempts.
Login caveat: this console sends fields to a local Matrix management room, then redacts them. Pruning is asynchronous and crashes/backups can retain them. This is not a guarantee that credentials never reach disk.
After creating the account, remove registration_shared_secret from runtime/synapse/homeserver.yaml and restart only Synapse. See stack operations.
Allow a conversation
Use the bridge console's help, search, resolve-identifier and start-chat commands to find an existing conversation and create its local Matrix room. Check the identity before selection.
.\.venv\Scripts\python.exe -m messenger_mcp invitations
.\.venv\Scripts\python.exe -m messenger_mcp join '!example:messenger.localhost'
.\.venv\Scripts\python.exe -m messenger_mcp rooms
.\.venv\Scripts\python.exe -m messenger_mcp allow '!example:messenger.localhost' 'Example contact'The local allow command shows metadata and asks for confirmation. AI tools cannot grant themselves access. Revoke removes MCP access and local cached text in the default allowlist mode; it does not erase Matrix, bridge, backup or AI-client copies.
To opt in to automatic access to joined Messenger chats, set chat_access to bridged in the private configuration. This mode reads the local mautrix-meta database to match rooms associated with the configured Matrix user and intersects them with current Matrix membership. Unbridged conversations, management rooms and spaces are excluded. The bridge still needs to create the rooms and the Matrix user needs to join them. Switch chat_access back to allowlist to use explicit room selection again.
Connect Codex or Claude
Generate machine-specific configuration:
.\.venv\Scripts\python.exe -m messenger_mcp clients --output runtime/clientsMerge the generated entry for your client, preserving other servers. Client instructions cover Codex, Claude Code and Claude Desktop. Snippets contain absolute launcher paths, not credentials; do not commit them.
No watcher is required: reads refresh automatically. Ask your assistant to list allowed chats, read recent messages or search a conversation.
Sending
New installations start with sending disabled. To allow text sends on your explicit instructions in the AI client:
.\.venv\Scripts\python.exe -m messenger_mcp sending directKeep client approval prompts for send_message. The server cannot prove an AI call originated from a human instruction. Use sending local_approval for a server-enforced local gate, followed by outbox and approve REQUEST_ID / reject REQUEST_ID. Use sending disabled to turn writes off immediately.
Each message needs a unique stable request_id. After a delay check get_send_status with that ID; never create a fresh ID just to retry. Uncertain sends cannot be replayed after the Matrix session changes. A crash in submitting requires reconciliation.
A client launched with --read-only does not receive sending tools.
Tools
Tool | Purpose |
get_status | Local readiness, without automatic login |
list_chats | Allowed conversations only |
get_messages | Fresh recent messages, optional sender/timestamp filters and cached-history cursor |
search_messages | Literal Unicode case-insensitive search of indexed text |
refresh_messages | Bounded refresh: 1–20 pages of 100 events |
send_message | Optional text send with a durable request ID |
get_send_status | Check without resending |
Reads accept refresh=false for offline access. A failed refresh returns sync.refreshed=false and sync.sync_error. Do not present those results as current.
Configuration and health
Use --config with an absolute path or MESSENGER_MCP_CONFIG. An editable checkout defaults to config.json in the project; an installed package otherwise uses the platform's user configuration directory. Relative data paths resolve against the configuration directory.
See config.example.json. allowed_rooms maps Matrix IDs to display names. bridge_database is optional local status evidence; without it status remains accepted until independently confirmed.
.\.venv\Scripts\python.exe -m messenger_mcp doctor
.\.venv\Scripts\python.exe -m messenger_mcp refresh --watchThe optional watcher refreshes the sole selected chat. It never retries Facebook authentication. The official bridge has its own connection and read-state behavior.
Privacy
Runtime databases, journals, session keys and cookies are sensitive. Restrict filesystem access and avoid shared-drive backups. Messenger E2EE terminates in the bridge; this prototype uses readable local Matrix rooms and a readable index. A stolen session is not constrained by our MCP allowlist.
Message text is untrusted data, never an instruction. AI clients may transmit requested messages to their model provider. Security details.
Development
python -m pip install -e .
python -m unittest discover -s tests -v
python tests/smoke_mcp.py
python scripts/check_release.pyTests use synthetic data, not a Facebook account. See CONTRIBUTING.md and third-party notices. This server is MIT licensed; upstream services retain their own licenses.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Hosted WhatsApp MCP server: read, search and reply to your own WhatsApp chats from your AI.
Your Telegram, WhatsApp, Instagram, mail and calendar in Claude or ChatGPT. Never sends messages.
Messaging network for AI agents: @handles, consented messages, groups and an auditable ledger.
Read-only WhatsApp MCP for your AI agent: it reads the chats you choose. Try the public demo.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to securely read from and interact with Matrix and Microsoft Teams chat under scoped, expiring, human-approved grants, with per-operation approval for sending and editing messages and no free access to room content.GPL 3.0
- AlicenseNot gradedqualityNot gradedmaintenanceLets an AI assistant read, search, and send messages in your own chats by linking to your account as a companion device and keeping a searchable archive of the history. It exposes tools for chats, people, groups, contacts, reactions, and message actions over MCP, running in your own Cloudflare account so the data stays with you.GPL 3.0
- AlicenseNot gradedqualityNot gradedmaintenanceEnables AI assistants to read, search, and send messages from your own linked account, keeping a searchable archive of your chats. Runs on your personal Cloudflare deployment with MCP tools for finding people, listing chats, and managing contacts.GPL 3.0
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to read your Mac's Messages database read-only and turn conversations into a queryable list of plans, commitments, follow-ups, owed replies, and facts your assistant can act on. Runs entirely on your Mac behind a local Unix-socket bridge, so message data stays local except for filtered conversation windows sent to your chosen interpreter.MIT