textbee SMS

@textbee/mcp

适用于 textbee.dev 的 MCP 服务。textbee.dev 是一款开源 SMS 网关，可将 Android 手机变成 SMS API。它让 Claude、Cursor 和任何 MCP 客户端都能通过你自己的手机和号码发送、读取 SMS。

提供三个工具，无需按消息付费，支持自托管的 textbee 实例。

设置

你需要拥有一个 textbee 账户、已配对的 Android 设备，以及从控制面板获取的 API 密钥。该密钥可访问整个账户；请像保护密码一样妥善保管。

claude.ai、Claude Desktop 和 Claude 移动应用（无需安装）

这些应用使用托管端点 https://mcp.textbee.dev/mcp，运行的工具与此软件包中的相同。

1. 在 claude.ai 或 Claude Desktop 中，打开 Customize，然后选择 Connectors、+ Add 和 Add custom connector。
2. 输入名称 textbee 和 URL https://mcp.textbee.dev/mcp，然后点击 Continue 两次。
3. 选择 Sign in now，保留推荐的 OAuth 客户端选项，然后点击 Add。
4. 在 textbee 登录页面粘贴你的 API 密钥，然后点击 Connect。

连接一次即可在网页、Claude Desktop 和 Claude 移动应用中使用（移动应用无法自行添加连接器）。在 Team 和 Enterprise 计划中，需由所有者先为组织添加连接器。连接有效期为 90 天，之后 Claude 会提示你重新连接。textbee 会验证密钥但不会存储密钥，不过密钥会经过 textbee 的服务器。如需断开连接，可在控制面板撤销密钥。若要将密钥保留在自己的设备上，请使用下面的本地设置。

Claude Code

本地配置，密钥保存在你自己的配置文件中：

claude mcp add textbee -s user -e TEXTBEE_API_KEY=your-key -- npx -y @textbee/mcp

或者使用托管服务，在浏览器中通过密钥登录：

claude mcp add --transport http -s user textbee https://mcp.textbee.dev/mcp

然后在 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：

{
  "mcpServers": {
    "textbee": {
      "command": "npx",
      "args": ["-y", "@textbee/mcp"],
      "env": { "TEXTBEE_API_KEY": "your-key" }
    }
  }
}

Cursor

在 ~/.cursor/mcp.json 中使用相同的对象。支持通过标头连接远程服务的客户端也可改用 https://mcp.textbee.dev/mcp，并将密钥作为 x-textbee-api-key 或 Authorization: Bearer <key> 发送。

完整设置指南：textbee.dev/docs/agents/mcp。

首次启动较慢

npx 首次运行时会下载软件包。如果客户端因等待超时，可先全局安装一次，然后将配置指向该二进制文件：

npm install -g @textbee/mcp

{ "mcpServers": { "textbee": { "command": "textbee-mcp", "env": { "TEXTBEE_API_KEY": "your-key" } } } }

工具

send_sms

向一个或多个接收者发送 SMS（E.164 格式，例如 +15550100123）。发送手机会自动选择：优先使用默认设备，否则使用最近发送心跳的已启用设备。可选参数包括 device_id、sim_subscription_id 和 scheduled_at。当账户使用 SMS 队列时，会返回用于检查投递状态的 sms_batch_id。

get_messages

读取账户中所有设备上的消息。默认读取收到的消息，并按时间从新到旧排序。可按 direction（received、sent、all）、自由文本 search、sms_batch_id（发送消息的逐接收者投递状态）、device_ids 以及 from/to 时间范围筛选。支持游标分页，可用于轮询而不产生重复或遗漏。

list_devices

账户中的手机：设备 ID、启用状态、默认发送设备、上次签到时间和消息数量。

自托管 textbee

将服务指向你自己的实例：

"env": {
  "TEXTBEE_API_KEY": "your-key",
  "TEXTBEE_BASE_URL": "https://sms.example.com"
}

/api/v1 后缀可选，并会自动添加。也支持通过子路径部署，例如 https://example.com/textbee。无效的 URL 会报错，而不是静默回退，因此即使 URL 拼写错误，也不会将你的密钥发送到公共 API。

环境变量

变量	必填	默认值	用途
TEXTBEE_API_KEY	是	无	从 textbee 控制面板获取的 API 密钥
TEXTBEE_BASE_URL	否	https://api.textbee.dev	自托管时你的实例 URL
TEXTBEE_TIMEOUT_MS	否	30000	每个请求的超时时间，单位为毫秒

说明

• 你的密钥会留在你的设备上：此服务只会与上述基础 URL 的 textbee API 通信。
• 发送操作会计入你的 textbee 套餐额度，并受服务端的套餐速率限制约束。
• 所有诊断信息都会输出到 stderr；stdout 专用于 MCP 协议。

将其用作库

此软件包还会导出工具定义，以便嵌入其他 MCP 主机（托管的远程端点正是通过这种方式复用这些定义）：

import { createTextbeeMcpServer, staticCredentials, loadConfig } from '@textbee/mcp'

const server = createTextbeeMcpServer({
  credentials: staticCredentials(loadConfig(process.env)),
})

凭据会针对每次工具调用解析，因此多租户主机可以为每个请求注入不同的密钥。请参阅 credentialsFromAuthInfoExtra。

许可证

MIT。属于 textbee 项目的一部分。