phone-sms

phone-sms

Site: https://phone-sms.vercel.app · Repo: https://github.com/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:

Tool	Does
list_threads	conversations, newest first, with the latest message; filter by contact or unread
read_thread	the last n messages of one conversation
find_contact	look up a contact by name or number fragment (from the phone's synced contacts)
send_sms	send a text, or a group text to several numbers

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

• Linux with a D-Bus session bus and KDE Connect (kdeconnectd, a current release; package kdeconnect). It does not need the Plasma desktop; it runs fine under GNOME, Hyprland, Sway…
• An Android phone with the KDE Connect app (F-Droid / 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.
• 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 PHONE_SMS_DEVICE=<id> (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 <thread_id> [-n 20]
phone-sms contact <name>
phone-sms send <number>... -m "text"
phone-sms                              # MCP server on stdio

How sending works

1. find_contact <name> gives the number; send_sms takes numbers, ideally in E.164 (+14375551234).
2. The model shows you recipient and text and waits for your yes.
3. send_sms answers handed to phone… once kdeconnectd has accepted the request. That is not delivery: the sent message shows up in list_threads / read_thread once the phone syncs it, usually within a minute.

Troubleshooting

• "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 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'".
• Names missing: enable the Contacts plugin on both ends; vCards land in ~/.local/share/kpeoplevcard/kdeconnect-<device>/.
• The kdeconnectd journal line Unimplemented conversation of type 'r' comes from the notification-forwarding plugin, not SMS.

Notes for hackers

It uses org.kde.kdeconnect.device.conversations, the interface the kdeconnect-sms app uses. The daemon object's introspection XML has duplicate methods, so device discovery is a raw D-Bus call. requestConversation first emits only cached messages, so read_thread waits for count messages or conversationLoaded, not for a quiet gap.

License

GPL-3.0-or-later, like KDE Connect.