@textbee/mcp

用于 textbee.dev 的 MCP 服务器，textbee.dev 是一个开源 SMS 网关，可将 Android 手机变成 SMS API。它为 Claude Desktop、Claude Code、Cursor 以及任何 MCP 客户端提供通过您自己的手机和号码发送和读取短信的能力。

三个工具，无逐条消息标记，支持自托管的 textbee 实例。

设置

您需要一个 textbee 账户、一台已配对的 Android 设备以及来自控制台的 API 密钥。该密钥拥有完整的账户访问权限，请像对待密码一样妥善保管。

Claude Code

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

Claude Desktop

添加到 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/claude_desktop_config.json）：

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

Cursor

在 ~/.mcp.json 中使用相同的对象：

npm install -g @textbee/mcp

首次启动较慢

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

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

Related MCP server: commune-mcp

工具

send_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 会直接报错，而不会静默回退，因此拼写错误绝不会将您的密钥发送到公共 API。

环境变量

备注

• 您的密钥只保存在您的机器上：此服务器仅与上述基础 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 项目的一部分。