Save 44% with yearly billing, 5 months free.View Plans
textbee Logotextbee.dev
Documentation

MCP server

Connect Claude, Cursor or any MCP client to textbee and send or read SMS through your own Android phone. Hosted connector or local npx server.

Updated

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

There are two ways to connect:

WayBest forYour API key
Hosted connector at https://mcp.textbee.dev/mcpclaude.ai, Claude Desktop, the Claude mobile apps, Claude CodeYou paste it once on a textbee sign-in page. textbee checks it and does not store it.
Local server with npx -y @textbee/mcpClaude Code, Claude Desktop, Cursor, any MCP client that runs a commandStays on your machine, in your client config.

The local server is published on npm as @textbee/mcp. It is open source, MIT licensed, source at github.com/textbee/textbee-mcp. The hosted connector runs the same tools.

Prerequisites

  • A textbee.dev account with a registered Android device
  • An API key from the dashboard. Create a separate key for your assistant, so you can revoke it on its own later.

Connect to Claude

claude.ai, Claude Desktop and the Claude mobile apps

Use the hosted connector. You need no Node.js and no config file.

  1. In claude.ai or Claude Desktop, open Customize, then Connectors.
  2. Click + Add, then Add custom connector.
  3. Enter the name textbee and the MCP server URL https://mcp.textbee.dev/mcp. Click Continue.
  4. Click Continue on the settings Claude detects. Under Authentication, choose Sign in now. Leave OAuth client on the recommended option. Click Add.
  5. The textbee sign-in page opens. Paste your API key and click Connect. If the page does not open, click Connect on the textbee connector.

The connector now works in claude.ai on the web, in Claude Desktop and in the Claude mobile apps. To use it in a chat, click the + button in the message box, open Connectors and turn on textbee.

  • Mobile apps: add the connector in claude.ai or Claude Desktop first. The mobile apps then use it with the same account.
  • Free plan: Claude allows one custom connector.
  • Team and Enterprise plans: an owner adds the connector in Organization settings, then Connectors. Each member then opens Customize, then Connectors, clicks Connect on textbee and pastes their own API key.
  • The connection lasts 90 days. After that, Claude asks you to reconnect. Click Connect and paste the key again.
  • To disconnect, revoke the API key in the dashboard. Removing the connector in Claude also stops it.
  • Without the sign-in page: under Authentication, choose No sign in, and under Request headers add x-textbee-api-key with your API key as the value. Claude then sends the key on every request and the connection does not expire.

Claude Code

Hosted, sign in once in the browser:

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

Then start Claude Code, run /mcp, select textbee and choose Authenticate. The textbee sign-in page opens in your browser. Paste your API key and click Connect.

Local, the key stays on your machine:

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

-s user makes the server available in every project. Run claude mcp list to check that it is connected.

Claude Desktop with a local server

Use this when you want the key to stay on your machine, or when you connect to a self-hosted instance. Claude Desktop needs Node.js for npx.

Add this to claude_desktop_config.json, then restart Claude Desktop:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
JSON
{
  "mcpServers": {
    "textbee": {
      "command": "npx",
      "args": ["-y", "@textbee/mcp"],
      "env": { "TEXTBEE_API_KEY": "your-key" }
    }
  }
}

Other MCP clients

Cursor

Add the same configuration object as Claude Desktop to ~/.cursor/mcp.json.

To use the hosted endpoint instead, send the API key in a header:

JSON
{
  "mcpServers": {
    "textbee": {
      "url": "https://mcp.textbee.dev/mcp",
      "headers": { "x-textbee-api-key": "your-key" }
    }
  }
}

Any other client

  • Clients that run a command use npx -y @textbee/mcp with TEXTBEE_API_KEY in the environment.
  • Clients that support remote servers with headers use https://mcp.textbee.dev/mcp and send the key as Authorization: Bearer <key> or x-textbee-api-key.
  • The browser sign-in works for Claude and for clients that receive the sign-in result on localhost. Editors such as Cursor and VS Code cannot use it. They use the header form.

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:

Shell
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. International format (for example +12015550123) works everywhere. See Phone number format. 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_number (pick a SIM on dual-SIM phones: 1 is SIM 1, 2 is SIM 2), 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

These apply to the local server.

  • 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

https://mcp.textbee.dev/mcp is a streamable HTTP endpoint with the same three tools and the same plan limits as the local server. It is stateless, so the client needs no session handling. It accepts two kinds of sign-in:

  • Sign-in page (OAuth). Claude opens the textbee sign-in page. You paste an API key, and textbee checks it against your account. Claude then gets an encrypted token that carries the key. textbee stores nothing. Claude refreshes the token on its own. The connection ends 90 days after the first sign-in.
  • Header. The client sends the key on every request as Authorization: Bearer <key> or x-textbee-api-key. No sign-in step.

With the hosted endpoint, your API key passes through textbee's server on every request. textbee does not log or store it. Revoke the key in the dashboard to disconnect every client that uses it. When your client can run npx and you want the key to stay on your machine, use the local server. The hosted endpoint talks to the textbee 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.
  • The local server writes all diagnostics to stderr. Stdout is reserved for the MCP protocol.

Troubleshooting

  • The local 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 connector shows "needs reconnect" or asks you to connect again. The 90-day connection ended or the key was revoked. Open Customize, then Connectors, and click Connect on the textbee connector. Paste a valid key on the sign-in page.
  • Claude Code lists textbee as needing authentication. Run /mcp, select textbee and choose Authenticate.
  • 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.
  • The sign-in fails before the textbee page opens. Remove the connector and add it again. Either OAuth client option works: Use Claude's published identity or Register automatically.
  • The sign-in fails with "redirect_uri not allowed". Your client cannot use the sign-in page. Send the key in a header instead, or use the local server.
  • The textbee tools do not appear in a Claude chat. Click the + button in the message box, open Connectors and turn on textbee.
  • Self-hosted instance returns 401. Check the base URL the local 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 local server at your own instance with TEXTBEE_BASE_URL

Need help? Check our FAQ or contact support.