Skip to main content
Glama
Messenger Local MCP

Messenger Local MCP

by Allowsik
README.md
# 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](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.

## 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:

~~~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 start
~~~

On 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:

~~~powershell
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-login
~~~

In 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](docs/stack.md).

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

~~~powershell
.\.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:

~~~powershell
.\.venv\Scripts\python.exe -m messenger_mcp clients --output runtime/clients
~~~

Merge the generated entry for your client, preserving other servers. [Client instructions](docs/clients.md) 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:

~~~powershell
.\.venv\Scripts\python.exe -m messenger_mcp sending direct
~~~

Keep 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](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.

~~~powershell
.\.venv\Scripts\python.exe -m messenger_mcp doctor
.\.venv\Scripts\python.exe -m messenger_mcp refresh --watch
~~~

The 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](SECURITY.md).

## Development

~~~powershell
python -m pip install -e .
python -m unittest discover -s tests -v
python tests/smoke_mcp.py
python scripts/check_release.py
~~~

Tests use synthetic data, not a Facebook account. See [CONTRIBUTING.md](CONTRIBUTING.md) and [third-party notices](THIRD_PARTY.md). This server is MIT licensed; upstream services retain their own licenses.