phone-sms MCP server

phone-sms

Site: https://phone-sms.vercel.app · Repo: https://github.com/h-3303/phone-sms

<!-- mcp-name: io.github.h-3303/phone-sms -->

An MCP server that lets Claude (or any MCP client) read and send SMS through your own Android phone, from your own number. It talks to the phone over KDE Connect on your local network: no cloud relay, no SMS gateway account, no app to install beyond KDE Connect itself.

agent ──MCP──▶ phone-sms ──D-Bus──▶ kdeconnectd ──LAN──▶ KDE Connect (Android) ──▶ SMS

Tools:

send_sms carries MCP's destructiveHint, and the server tells the model never to send until you have approved the exact recipient and text in the conversation. Message contents never leave your machine except as the model's context.

Requirements

kdeconnect). It does not need the Plasma desktop; it runs fine under GNOME, Hyprland, Sway…

• Linux with a D-Bus session bus and KDE Connect (kdeconnectd, a current release; package

Play), paired with the computer. On the phone, enable the SMS plugin (and Contacts if you want names) and grant the SMS and contacts permissions it asks for.

• An Android phone with the KDE Connect app (F-Droid /

• uv and Python 3.12+.

Check the pairing: kdeconnect-cli -l should list your phone as paired and reachable.

Install

Claude Code, as a plugin (one step):

/plugin marketplace add h-3303/phone-sms
/plugin install phone-sms@phone-sms

Claude Code, as a plain MCP server:

claude mcp add --scope user phone-sms -- uvx phone-sms

Any other MCP client (Claude Desktop config shape, Cursor, Zed, …):

{
  "mcpServers": {
    "phone-sms": {
      "command": "uvx",
      "args": ["phone-sms"]
    }
  }
}

From a checkout: uv run --directory /path/to/phone-sms -q phone-sms.

The server uses the first paired, reachable device. With several phones, pin one with PHONESMSDEVICE= (the id kdeconnect-cli -l prints).

CLI

The same code paths, for checking things by hand:

phone-sms threads [-n 20] [--unread] phone-sms read [-n 20] phone-sms contact phone-sms send ... -m "text" phone-sms # MCP server on stdio

How sending works

delivery: the sent message shows up in listthreads / readthread once the phone syncs it, usually within a minute.

1. findcontact gives the number; sendsms takes numbers, ideally in E.164 (+14375551234).
2. The model shows you recipient and text and waits for your yes.
3. sendsms answers handed to phone…* once kdeconnectd has accepted the request. That is not

Troubleshooting

and that Android granted KDE Connect the SMS permission. Watch the request leave the server with dbus-monitor --session "interface='org.kde.kdeconnect.device.conversations',member='sendWithoutConversation'".

• "no paired, reachable device": open KDE Connect on the phone, same Wi-Fi, kdeconnect-cli -l.
• Sent, but nothing arrives: on the phone, check that the SMS plugin is enabled for this computer

~/.local/share/kpeoplevcard/kdeconnect-/.

• Names missing: enable the Contacts plugin on both ends; vCards land in

notification-forwarding plugin, not SMS.

• The kdeconnectd journal line Unimplemented conversation of type 'r' comes from the

Notes for hackers

Shortened. The full README is on GitHub.