用途
textbee-mcp 是 textbee.dev 的 MCP 服务器。textbee.dev 是开源短信网关，能把一部 Android 手机变为短信 API。该服务器让 Claude、Cursor 以及任何 MCP 客户端能够通过你自己的手机和号码发送、读取短信。
主要能力
提供三个工具：
- 发送短信：可发送给一个或多个收件人（E.164 格式，例如 +15550100123）。发送手机自动选择：默认设备，否则选最近有心跳的已启用设备。可选参数包括 device_id、sim_subscription_id、scheduled_at。当账户使用 SMS 队列时，返回 sms_batch_id 用于投递检查。
- 读取消息：读取账户下所有设备的短信，默认按接收时间倒序显示收到的消息。可按方向（received、sent、all）、自由文本搜索、sms_batch_id（某次发送的逐收件人投递状态）、device_ids 以及 from/to 时间窗口进行筛选。支持游标分页，便于轮询而不重复或遗漏。
- 查看设备：列出账户中的手机，包括 id、启用状态、默认发送设备、最后签到时间以及消息数量。
使用方式
使用前需要：具有已配对 Android 设备的 textbee 账户，以及从仪表盘获取的 API 密钥。密钥拥有完整账户访问权限，应像密码一样妥善保管。
托管端点（无需安装，适用于 claude.ai、Claude Desktop 和 Claude 移动应用）： 使用托管端点 https://mcp.textbee.dev/mcp，其运行的工具与本包相同。在 claude.ai 或 Claude Desktop 中，打开 Customize，进入 Connectors，点击 + Add 并选择 Add custom connector。输入名称 textbee 和 URL https://mcp.textbee.dev/mcp，然后连续点击两次 Continue。选择 Sign in now，OAuth 客户端保留推荐选项，点击 Add。在 textbee 登录页粘贴 API 密钥并点击 Connect。一个连接即可用于网页版、Claude Desktop 和 Claude 移动应用（移动应用本身不能添加连接器）。在 Team 和 Enterprise 计划中，需由所有者先为组织添加连接器。连接有效期为 90 天，之后 Claude 会要求重新连接。textbee 会检查密钥但不存储它，密钥会经过 textbee 的服务器。可在仪表盘撤销密钥以断开连接。若想让密钥只留在本机，请使用下方的本地设置。
本地使用（密钥放在自己的配置中）： 支持两种方式：本地运行，密钥写入配置；或使用托管端点，在浏览器中登录并提交密钥。 然后在 Claude Code 中运行 /mcp，选择 textbee，并选择 Authenticate。
Claude Desktop 本地配置： 将配置对象添加到 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/claude_desktop_config.json；Windows：%APPDATA%\Claude\claude_desktop_config.json），然后重启 Claude Desktop。Cursor 使用 ~/.cursor/mcp.json 中的同一对象。支持带请求头的远程服务器客户端可改用 https://mcp.textbee.dev/mcp，并通过 x-textbee-api-key 或 Authorization: Bearer <key> 发送密钥。完整设置指南见 textbee.dev/docs/agents/mcp。
首次启动较慢： npx 首次运行会下载包。如果客户端等待超时，可先全局安装一次，再将配置指向该二进制文件。
自托管 textbee： 将服务器指向你自己的实例。/api/v1 后缀可选，会自动添加。像 https://example.com/textbee 这样的子路径部署也可用。无效 URL 会报错而不是静默回退，因此拼写错误不会把你的密钥发往公共 API。
环境变量： 密钥保留在你的机器上：此服务器只与上述基础 URL 的 textbee API 通信。发送量计入你的 textbee 计划配额，计划的速率限制在服务端适用。所有诊断信息输出到 stderr；stdout 保留给 MCP 协议。
作为库使用： 该包也导出其工具定义，可嵌入另一个 MCP 宿主（托管远程端点就是这样复用它们的）。凭据按每次工具调用解析，因此多租户宿主可为每个请求注入不同的密钥。参见 credentialsFromAuthInfoExtra。
适用场景
适合需要通过自有号码让 AI 代理发送和接收短信的场景，如回复消息、验证码、投递状态查询等，也支持自托管 textbee 实例，便于对数据流向有要求的用户。
限制
- 需要 textbee 账户、已配对的 Android 设备以及 API 密钥。
- API 密钥拥有完整账户访问权限，需谨慎保管；使用托管端点时密钥会经过 textbee 服务器，可改用本地设置或撤销密钥断开。
- 托管连接有效期 90 天，之后需重新连接。
- 发送量计入 textbee 计划配额，速率限制由服务端执行。
- 项目采用 MIT 许可证，是 textbee 项目的一部分。
- 其他细节暂未提供。
