textbee Logotextbee.dev
Plans from $9.99/mo.View Plans
Documentation

MCP server

Connect Claude, Cursor, or any MCP-enabled AI agent to textbee with the official @textbee/mcp server. Send and read SMS through your own Android phone from a conversation.

The official MCP (Model Context Protocol) server for textbee, 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

The API key stays on your machine, inside your own MCP client config. The server only ever talks to the textbee API.

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 +15550100123). 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.

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.

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 (claude.ai on the web, ChatGPT connectors, some mobile apps), textbee runs a hosted streamable HTTP endpoint:

https://mcp.textbee.dev/mcp

Authenticate every request with your API key, as Authorization: Bearer <key> or the x-textbee-api-key header. Same three tools, same plan limits. The endpoint is stateless, so it needs no session handling from the client.

With the hosted endpoint your API key passes through textbee's server on every request. It is used only for that request and never logged or stored, but it does leave your machine. When your client can run npx, prefer the local server above. The hosted endpoint talks to the cloud API only; self-hosted instances use the local server with TEXTBEE_BASE_URL.

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.
  • 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

Need help? Check our FAQ or contact support.

Previous
JavaScript
Next
Agent quickstart