Skip to main content
Glama

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:

  1. Install the project

  2. Hear the plugin answer from its made-up device

  3. Put matrix-door in front of the inbox

  4. Set up Synapse behind the door

  5. Start ntfy behind the door

  6. Bridge Messenger with mautrix-meta

  7. 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=ignore

Check: 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.toml

Check: 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=$USER

To 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:8008

Check: 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/versions

Check: 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 messages

Check: claude-voice plugins list shows messages as approved.

What is where

Part

What it is for

src/messages_mcp/server.py

The MCP tools. Each answer carries a say, the sentence the voice reads aloud.

src/messages_mcp/service.py

The core: it asks the gizmo and words every answer, failures included.

src/messages_mcp/device.py

What the service needs from a gizmo. A real adapter answers it.

src/messages_mcp/fake.py

A made-up gizmo that refuses what the real one refuses.

src/messages_mcp/settings.py

The plugin's own config, from its own folder.

src/messages_mcp/platform/

The one place that knows the operating system.

scripts/ratchet.py

The quality levels, which may never get worse than main's.

scripts/mutate.py

Switches each rule off in turn, to prove its test can fail.

scripts/docs.py

Makes this page's step list from docs/setup.md.

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 ratchet

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

  1. While scripts/.mutate-recovery.json exists, a mutation run of yours still has a line switched off. Stop that run with SIGTERM, and it puts the line back itself.

  2. Run the repair, which puts back a line a killed run left and runs nothing else.

  3. Check that git status shows nothing. A plain git worktree remove refuses a worktree with changes, and that refusal is the point: never add --force.

  4. 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…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Give 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.
      27
      1
      Apache 2.0
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables Claude to read, organize, and send SMS messages through your ClickSend account.
      -
    • A
      license
      A
      quality
      B
      maintenance
      Enables Claude on macOS to read, search, and send iMessage, SMS, and RCS messages, with tools for stats, chat history, attachments, and message composition.
      9
      2
      MIT