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:
| Way | Best for | Your API key |
|---|---|---|
Hosted connector at https://mcp.textbee.dev/mcp | claude.ai, Claude Desktop, the Claude mobile apps, Claude Code | You paste it once on a textbee sign-in page. textbee checks it and does not store it. |
Local server with npx -y @textbee/mcp | Claude Code, Claude Desktop, Cursor, any MCP client that runs a command | Stays 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.
- In claude.ai or Claude Desktop, open Customize, then Connectors.
- Click + Add, then Add custom connector.
- Enter the name
textbeeand the MCP server URLhttps://mcp.textbee.dev/mcp. Click Continue. - Click Continue on the settings Claude detects. Under Authentication, choose Sign in now. Leave OAuth client on the recommended option. Click Add.
- 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-keywith 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:
claude mcp add --transport http -s user textbee https://mcp.textbee.dev/mcpThen 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:
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
{
"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:
{
"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/mcpwithTEXTBEE_API_KEYin the environment. - Clients that support remote servers with headers use
https://mcp.textbee.dev/mcpand send the key asAuthorization: Bearer <key>orx-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:
npm install -g @textbee/mcpThen 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/v1suffix is optional and added automatically; subpath deployments likehttps://example.com/textbeework 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>orx-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_KEYenv 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_idfromlist_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, selecttextbeeand 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.