MCP server

The official MCP (Model Context Protocol) server for textbee lets an AI assistant send and read SMS through your own Android phone. Add it to your MCP client with your API key, and the assistant gets three tools: send_sms, get_messages and list_devices.

The server is published on npm as @textbee/mcp. It gives Claude Desktop, Claude Code, Cursor, and any MCP-compatible client the ability to send and read SMS through your textbee account. Open source, MIT licensed, source at github.com/textbee/textbee-mcp.

Prerequisites

• A textbee.dev account with a registered Android device
• An API key from the dashboard

Install

Claude Code

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

Claude Desktop

Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json), then restart Claude Desktop:

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

Cursor

The same configuration object in ~/.cursor/mcp.json.

Slow first start

npx downloads the package on first run. If your client times out waiting, install globally once and point the config at the binary:

npm install -g @textbee/mcp

Then use "command": "textbee-mcp" with no args.

Tools

The server exposes three tools. Small surfaces work better with agents, and these cover the full send-and-read loop.

send_sms

Sends a message to one or more recipients in international E.164 format (for example +12015550123). The sending phone is chosen automatically: your default device, otherwise the enabled device with the most recent heartbeat. Optional parameters: device_id (send from a specific phone), sim_subscription_id (pick a SIM on dual-SIM phones), scheduled_at (send later). When your account uses the SMS queue, the result includes an sms_batch_id for delivery checks. The API accepted the message at this point. It is not yet delivered. See Delivery status for what each state means.

get_messages

Reads messages across every device on the account, no device id needed. Filters: direction (received by default, or sent / all), free-text search, sms_batch_id (the per-recipient delivery status of a send), device_ids, and a from/to time window. Supports cursor pagination, so an agent can poll for new messages without missing or repeating any. The tool reads the same data as message history.

list_devices

The phones on the account: ids, enabled state, which one sends by default, last check-in, and message counts.

Environment variables

• TEXTBEE_API_KEY (required): API key from the textbee dashboard.
• TEXTBEE_BASE_URL (optional): your instance URL when self-hosting. Defaults to https://api.textbee.dev. The /api/v1 suffix is optional and added automatically; subpath deployments like https://example.com/textbee work too. An invalid URL is an error rather than a silent fallback, so a typo never sends your key to the public API.
• TEXTBEE_TIMEOUT_MS (optional): per-request timeout in milliseconds. Defaults to 30000.

Hosted endpoint

For clients that cannot launch a local process, textbee runs a hosted streamable HTTP endpoint with the same three tools and the same plan limits:

https://mcp.textbee.dev/mcp

claude.ai and the Claude apps

1. In claude.ai, open Settings, then Connectors, then Add custom connector.
2. Enter a name such as textbee and the URL https://mcp.textbee.dev/mcp. Leave the advanced settings empty.
3. Click Connect. A textbee sign-in page opens.
4. Paste an API key from the dashboard and click Connect.

The connector then works in claude.ai on the web, Claude Desktop and the Claude mobile apps. On Team and Enterprise plans, an owner adds custom connectors for the organization first.

Clients that accept headers

Send your API key on every request as Authorization: Bearer <key> or the x-textbee-api-key header. No sign-in step is needed. The endpoint is stateless, so it needs no session handling from the client.

Notes

• Sends count against your textbee plan quota, and plan limits are enforced server-side. An agent cannot outspend your plan.
• Reading messages does not consume the send quota.
• All diagnostics go to stderr; stdout is reserved for the MCP protocol.

Troubleshooting

• The server starts but every call fails with a key error. The TEXTBEE_API_KEY env value is missing or revoked. Create a fresh key in the dashboard and restart your client.
• A send fails with "No enabled device found". Enable a device in the textbee Android app or the dashboard, or pass a specific device_id from list_devices.
• The claude.ai connector shows "needs reconnect". Open Settings, then Connectors, and click Connect on the textbee connector. If you revoked the API key, paste a new one on the sign-in page.
• The textbee sign-in page says the key was not accepted. Copy the full key again from the dashboard. A revoked key does not work.
• Self-hosted instance returns 401. Check the base URL the server prints in its startup line; it shows exactly which API it is talking to.

Next steps

• Agent quickstart - The raw API endpoints agents should use
• n8n - No-code SMS automation
• Webhooks - Push incoming messages to your own systems
• Self-hosting - Point the server at your own instance with TEXTBEE_BASE_URL

Need help? Check our FAQ or contact support.