messages-mcp
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.
messages-mcp
Messages by voice: SMS and chat messages, read from a Matrix inbox of your own. This is an MCP server that a voice assistant reaches through claude-voice, as one of its plugins.
It is being built in slices. For now it holds only the template's walking skeleton: one tool,
messages_status, answered by a made-up gizmo in fake.py. The reading tools replace it.
It started from claude-voice's plugin template. The guide for writing one is
docs/write-a-plugin.md in claude-voice, and docs/plugin-standard.md there holds the rules.
What you need first
Linux with systemd user units, Tailscale, uv, Python 3.12 or newer, and claude-voice. Five services run beside the plugin: matrix-door, Synapse, Element, ntfy and mautrix-meta.
Related MCP server: claude-imessage-mcp
Setting it up
The setup guide, docs/setup.md, is written so an agent can follow it alone. Every step there has a check. Some steps only the owner can do, and they are listed in full here.
The steps, in full, are in docs/setup.md:
Install the project
Hear the plugin answer from its made-up device
Put matrix-door in front of the inbox
Set up Synapse behind the door
Start ntfy behind the door
Bridge Messenger with mautrix-meta
Add the plugin to claude-voice
Steps only the owner can do
A. Keep the laptop awake with its lid closed
Why: these are system files, which need sudo on the owner's machine.
Put these lines in /etc/systemd/logind.conf.d/lid.conf. They take effect at the next boot.
Do not restart logind for them, since that can end the desktop session.
[Login]
HandleLidSwitch=ignore
HandleLidSwitchExternalPower=ignoreCheck: systemd-analyze cat-config systemd/logind.conf shows both lines.
B. List the devices that may reach the inbox
Why: who gets in is the owner's choice, and no tool or agent ever writes this list.
Take the phone's and this laptop's IDs from tailscale status --json. They are the ID of
Self and of the phone under Peer. Write them to ~/.config/messages-mcp/door.toml, with
only the owner able to read it. The file's exact form comes with matrix-door.
chmod 600 ~/.config/messages-mcp/door.tomlCheck: stat -c %a ~/.config/messages-mcp/door.toml prints 600.
C. Install Synapse and ntfy
Why: it installs packages on the owner's machine, with sudo. The operator setting also lets the
owner's user drive Tailscale without sudo, which widens who can change it.
Install both with the system's package manager, as each project's install docs say. If
tailscale cert needs root for the owner's user, let it run without:
sudo tailscale set --operator=$USERTo undo it, run sudo tailscale set --operator=.
Check: command -v ntfy prints a path, and tailscale cert --help runs without sudo.
D. Create the Matrix user
Why: the password is the owner's, and only the owner types it.
register_new_matrix_user -c ~/.local/share/synapse/homeserver.yaml http://127.0.0.1:8008Check: the owner can log in with it in step E.
E. Log in to Element on the laptop and the phone
Why: it is a login, and the recovery key is a secret only the owner keeps.
Log in on both, verify each against the other, and keep the recovery key somewhere safe.
Check: in Element's sessions list, both sessions show as verified.
F. Try the door from a device that is not on the list
Why: only the owner can reach the other devices on the tailnet.
From another laptop on the tailnet, try the inbox:
curl -sS https://<laptop>.<tailnet>.ts.net:8448/_matrix/client/versionsCheck: the connection is refused, and ~/.local/state/messages-mcp/door.log has a new line.
G. Paste the tailnet rule, and give the phone its push token
Why: the rule is a policy in the owner's own Tailscale account, and the token is a secret.
Paste the prepared rule into the Tailscale admin page. It gives only the phone and the laptop port 8448 and ntfy's port. Install the ntfy app on the phone, and give it its token.
Check: the ntfy app shows its topic as connected.
H. Log in to Messenger through the bridge
Why: it is a login to the owner's own account, with Messenger's encryption PIN.
Install mautrix-meta from its release page, then log in to account 1 in a plain terminal. Account 2 follows a week later, if account 1 had no lock.
Check: the bridge's management room in Element says the account is logged in.
I. Approve the plugin
Why: claude-voice runs a new plugin only once its owner has typed its name.
Do this only once the voice's private mark and its denies are in claude-voice.
claude-voice plugins approve messagesCheck: claude-voice plugins list shows messages as approved.
What is where
Part | What it is for |
| The MCP tools. Each answer carries a |
| The core: it asks the gizmo and words every answer, failures included. |
| What the service needs from a gizmo. A real adapter answers it. |
| A made-up gizmo that refuses what the real one refuses. |
| The plugin's own config, from its own folder. |
| The one place that knows the operating system. |
| The quality levels, which may never get worse than main's. |
| Switches each rule off in turn, to prove its test can fail. |
| Makes this page's step list from |
The checks
Every check is a recipe in the justfile, and CI runs the same lines.
just check runs the ones a pull request needs, with no network.
just check
just commits
just ratchetA new test must fail on the code before it, and the red-first job proves that. It runs only
the test files a change touches. So it does not see a change to shared test setup, such as
tests/conftest.py; say that in the pull request.
A rule is a line marked # RULE: what it says. Each one needs a test with its words as the
name, and a row in scripts/mutations/.
A commit may carry Co-Authored-By and an outside contributor's Signed-off-by, and no other
trailers. Any other note
belongs in the pull request's text. just setup turns on the hook that says so early.
Cleaning up your own worktree
A session that worked in a worktree of its own removes it when it is done. Do it in this order.
While
scripts/.mutate-recovery.jsonexists, a mutation run of yours still has a line switched off. Stop that run with SIGTERM, and it puts the line back itself.Run the repair, which puts back a line a killed run left and runs nothing else.
Check that
git statusshows nothing. A plaingit worktree removerefuses a worktree with changes, and that refusal is the point: never add--force.Remove the worktree. Each run's temporary folder went with the run itself.
kill -TERM <the mutation run's process>
uv run python scripts/mutate.py --repair-only
git status --short
git worktree remove <the worktree's path>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
Your own WhatsApp in Claude and ChatGPT: read chats, draft replies, send messages you approve.
Connect any IMAP/SMTP mailbox to Claude & ChatGPT: search, read, sort, draft. Sends only with OK.
Read and answer your team's WhatsApp and email inbox from Claude or ChatGPT. OAuth sign-in.
Let Claude or ChatGPT search, read and send your WhatsApp messages over MCP. OAuth sign-in.
Related MCP Servers
AlicenseAqualityDmaintenanceGive Claude (or any MCP client) a real email inbox and SMS. Your AI agent can read and send email, manage inboxes, track delivery, and handle SMS.271Apache 2.0- AlicenseNot gradedqualityDmaintenanceEnables Claude to send and receive iMessage/SMS messages through macOS, with support for attachments, chat history, and real-time message monitoring.MIT
- FlicenseNot gradedqualityCmaintenanceEnables Claude to read, organize, and send SMS messages through your ClickSend account.-
- AlicenseAqualityBmaintenanceEnables Claude on macOS to read, search, and send iMessage, SMS, and RCS messages, with tools for stats, chat history, attachments, and message composition.92MIT