phone-sms

phone-sms

网站： https://phone-sms.vercel.app · 仓库： https://github.com/h-3303/phone-sms

一个 MCP 服务，让 Claude（或任何 MCP 客户端）通过你自己的 Android 手机，以你自己的号码读取和发送 SMS。它通过本地网络上的 KDE Connect 与手机通信：没有云中继、没有 SMS 网关账户，也无需安装 KDE Connect 以外的应用。

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

工具：

工具	功能
list_threads	按最新时间倒序列出对话，并显示最新消息；可按联系人或未读状态筛选
read_thread	读取某个对话的最后 n 条消息
find_contact	根据姓名或号码片段查找联系人（来自手机同步的联系人）
send_sms	发送短信，或向多个号码群发短信

send_sms 带有 MCP 的 destructiveHint，且服务会告知模型：在你于对话中批准确切的收件人和文本之前，绝不能发送。除作为模型上下文外，消息内容不会离开你的设备。

要求

• Linux，配有 D-Bus 会话总线和 KDE Connect（kdeconnectd，当前版本；软件包为 kdeconnect）。不需要 Plasma 桌面；在 GNOME、Hyprland、Sway 等环境下也能正常运行。
• 一部安装了 KDE Connect 应用的 Android 手机（F-Droid / Play），并已与电脑配对。 在手机上启用 SMS 插件（如需显示姓名，也启用 Contacts），并授予应用请求的 SMS 和 联系人权限。
• uv 和 Python 3.12+。

检查配对状态：kdeconnect-cli -l 应将你的手机列为已配对且可连接。

安装

Claude Code，作为插件使用（一步完成）：

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

Claude Code，作为普通 MCP 服务使用：

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

其他任何 MCP 客户端（Claude Desktop 配置格式、Cursor、Zed 等）：

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

技能文件（告诉 Agent 何时以及如何使用这些工具，包含审批规则、OTP 操作步骤和摘要操作步骤）。上面的 Claude Code 插件已包含该文件；对于 Cursor、Codex、Copilot、Gemini CLI 等其他工具：

npx skills add h-3303/phone-sms

技能文件采用 MIT 许可（参见 plugin/skills/phone-sms/）；也已列入技能市场。服务仍采用 GPL 许可，并由上述命令从 PyPI 安装。

为什么选择它，而不是中继服务

	phone-sms	TextBee、SimLink、SMS8	ADB / Termux 服务	Twilio 风格的 MCP	mac Messages MCP
使用自己的号码	是	是，使用自己的 SIM 卡	是	否，使用租用的号码	是，通过 iPhone
云中继	无	使用对方的服务器，或自行托管	无	有	无
要求	Linux + KDE Connect	Android 应用 + 账户或 API 密钥	USB 调试，或在手机上安装 Termux	账户、美国流量需注册 A2P 10DLC、按消息收费	macOS、完整磁盘访问权限
读取收件箱	是	是	是	仅限租用号码的通信记录	是

如果你需要为产品提供电话号码，请选择中继服务。如果你希望 Agent 读取并回复你自己的短信，且使用 Linux，请选择 phone-sms。

从本地检出目录运行：uv run --directory /path/to/phone-sms -q phone-sms。

服务会使用第一个已配对且可连接的设备。如果有多部手机，可使用 PHONE_SMS_DEVICE=<id> 指定一部（kdeconnect-cli -l 会显示设备 ID）。

CLI

使用相同的代码路径，方便手动检查：

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                              # 通过 stdio 运行 MCP 服务

发送方式

1. find_contact <name> 会返回号码；send_sms 接受号码，最好使用 E.164 格式（+14375551234）。
2. 模型会向你显示收件人和短信内容，并等待你确认。
3. kdeconnectd 接受请求后，send_sms 会回复 已交给手机处理…。这不代表短信已送达：手机同步后，已发送的短信会显示在 list_threads / read_thread 中，通常在一分钟内完成。

安全与隐私

• 仅限本地。 服务只与 D-Bus 会话总线通信，不会连接其他任何内容。唯一的网络传输是 KDE Connect 在你的电脑和手机之间通过局域网建立的加密连接。服务不会打开套接字，也没有账户、API 密钥或遥测。
• 模型能看到的内容。 仅限工具针对你的请求返回的内容：会话列表以及你要求读取的消息。联系人姓名来自 KDE Connect 已同步到 ~/.local/share/kpeoplevcard/ 的 vCard。服务不会将任何内容写入磁盘。
• 发送有双重把关。 send_sms 标注了 destructiveHint；服务说明和技能都要求模型向你显示确切的收件人和短信内容，并在对话中等待你确认；在 Claude Code 中，工具权限提示则是第二道关卡。支持向少数几人发送群组短信；刻意不支持向列表批量发送。
• 供应链。 纯 Python，只有两个依赖项（mcp、dbus-next），通过 PyPI 可信发布由 GitHub Actions 发布；插件会固定到确切版本。可审查的代码：src/ 中共 340 行。
• 隐私页面：https://phone-sms.vercel.app/privacy。请在 issue tracker 中报告问题。

故障排查

• “没有已配对且可连接的设备”：在手机上打开 KDE Connect，确保连接到同一 Wi-Fi，并运行 kdeconnect-cli -l。
• 已发送，但没有收到：在手机上检查是否已为这台电脑启用 SMS 插件，以及 Android 是否已授予 KDE Connect SMS 权限。使用 dbus-monitor --session "interface='org.kde.kdeconnect.device.conversations',member='sendWithoutConversation'" 查看请求是否已从服务发出。
• 缺少姓名：在两端都启用 Contacts 插件；vCard 会存放在 ~/.local/share/kpeoplevcard/kdeconnect-<device>/。
• kdeconnectd 日志中的 Unimplemented conversation of type 'r' 来自通知转发插件，与 SMS 无关。

开发者须知

它使用 org.kde.kdeconnect.device.conversations，也就是 kdeconnect-sms 应用使用的接口。守护进程对象的 introspection XML 中存在重复方法，因此设备发现通过原始 D-Bus 调用完成。requestConversation 最初只会发送缓存的消息，因此 read_thread 会等待收到 count 条消息或 conversationLoaded，而不是等待一段无新消息的间隔。

许可证

服务采用 GPL-3.0-or-later 许可证，与 KDE Connect 相同。plugin/skills/phone-sms/ 中的技能文件采用 MIT 许可证，以便技能市场重新分发。

---

由 Moirai Digital 构建。