textbee-mcp
OfficialSend and read SMS through the user's textbee account and Android phone.
Send SMS to one or many phone numbers or short codes, optionally from a chosen device or SIM, or scheduled for later, with delivery/batch info when queueing is enabled.
Read messages across all devices, filter by direction, search text, device, time window, or SMS batch, and paginate/poll without duplicates or gaps.
List registered Android devices with IDs, enabled/default status, last check-in, and message counts.
Sends and reads SMS through the Android phones registered to the user's textbee account, which turns a phone into an SMS API. Exposes tools to send messages (optionally from a specific device or SIM, or scheduled for later), read received/sent messages across all devices with time-window and search filters, and list registered phones with their ids, enabled state, default-sender status, last check-in, and message counts.
@textbee/mcp
MCP server for textbee.dev, the open source SMS gateway that turns an Android phone into an SMS API. Gives Claude, Cursor, and any MCP client the ability to send and read SMS through your own phone and your own number.
Three tools, no per-message markup, works with self-hosted textbee instances.
Setup
You need a textbee account with a paired Android device and an API key from the dashboard. The key has full account access; treat it like a password.
claude.ai, Claude Desktop, and the Claude mobile apps (no install)
These use the hosted endpoint at https://mcp.textbee.dev/mcp, which runs the same tools from this package.
In claude.ai or Claude Desktop, open Customize, then Connectors, then + Add and Add custom connector.
Enter the name
textbeeand the URLhttps://mcp.textbee.dev/mcp, then click Continue twice.Choose Sign in now, leave the OAuth client on the recommended option, and click Add.
Paste your API key on the textbee sign-in page and click Connect.
One connection works on the web, in Claude Desktop, and in the Claude mobile apps (the mobile apps cannot add connectors themselves). On Team and Enterprise plans, an owner adds the connector for the organization first. It lasts 90 days, then Claude asks you to reconnect. textbee checks the key and does not store it, but the key does pass through textbee's server. Revoke the key in the dashboard to disconnect. To keep the key on your machine, use the local setup below.
Claude Code
Local, with the key in your own config:
claude mcp add textbee -s user -e TEXTBEE_API_KEY=your-key -- npx -y @textbee/mcpOr hosted, signing in with your key in the browser:
claude mcp add --transport http -s user textbee https://mcp.textbee.dev/mcpThen run /mcp in Claude Code, select textbee, and choose Authenticate.
Claude Desktop (local)
Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\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 object in ~/.cursor/mcp.json. Clients that support remote servers with headers can use https://mcp.textbee.dev/mcp instead and send the key as x-textbee-api-key or Authorization: Bearer <key>.
Full setup guide: textbee.dev/docs/agents/mcp.
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{ "mcpServers": { "textbee": { "command": "textbee-mcp", "env": { "TEXTBEE_API_KEY": "your-key" } } } }Related MCP server: clicksend-mcp
Tools
send_sms
Send an SMS to one or more phone numbers or short codes. Recipients are sent as given. A local number or short code reaches recipients in the sending phone's country. For a number in another country, use international format with the country code (for example +15550100123). The sending phone is chosen automatically: your default device, otherwise the enabled device with the most recent heartbeat. Optional device_id, sim_number, sim_subscription_id, and scheduled_at. sim_number picks the SIM: 1 for SIM 1, 2 for SIM 2. Omit it and the phone uses its default SIM. If the SIM slot is empty, the message fails and is never sent from another SIM. sim_subscription_id is an older option. Android can change it after a SIM swap, so prefer sim_number. If both are given, only sim_number is used. Returns an sms_batch_id for delivery checks when the account uses the SMS queue.
get_messages
Read messages across every device on the account. Defaults to received messages, newest first. Filter by direction (received, sent, all), free-text search, sms_batch_id (per-recipient delivery status of a send), device_ids, and a from/to time window. Supports cursor pagination for polling without duplicates or gaps.
list_devices
The phones on the account: ids, enabled state, which one sends by default, last check-in, and message counts.
Self-hosted textbee
Point the server at your own instance:
"env": {
"TEXTBEE_API_KEY": "your-key",
"TEXTBEE_BASE_URL": "https://sms.example.com"
}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.
Environment variables
Variable | Required | Default | Purpose |
| yes | none | API key from the textbee dashboard |
| no |
| Your instance's URL when self-hosting |
| no |
| Per-request timeout in milliseconds |
Notes
Your key stays on your machine: this server talks only to the textbee API at the base URL above.
Sends count against your textbee plan quota, and the plan's rate limits apply server-side.
All diagnostics go to stderr; stdout is reserved for the MCP protocol.
Using it as a library
The package also exports its tool definitions for embedding in another MCP host (this is how the hosted remote endpoint reuses them):
import { createTextbeeMcpServer, staticCredentials, loadConfig } from '@textbee/mcp'
const server = createTextbeeMcpServer({
credentials: staticCredentials(loadConfig(process.env)),
})Credentials are resolved per tool call, so a multi-tenant host can inject a different key per request. See credentialsFromAuthInfoExtra.
License
MIT. Part of the textbee project.
Available Tools
3 toolsget_messagesRead messagesARead-only
Read the SMS messages on the user's textbee account, covering every device, no device id needed. direction defaults to "received": checking for a reply or a one-time code is the usual case. Pass direction "sent" to review what went out (each row carries its delivery status), or "all" for a conversation in order. Pass the sms_batch_id from a send to see that send's per-recipient delivery status. To poll for new messages without missing or repeating any: use order "asc" with a from bound, then keep calling with the next_cursor each result prints. from is inclusive and to is exclusive, so consecutive windows tile exactly. Reading does not consume the plan send quota. Messages reach textbee within a few seconds of arriving on the phone, so when waiting for a code, wait briefly and call again rather than tight-polling.
Inputs: to, from, limit, order, +5 more.
list_devicesList devicesARead-only
List the Android phones registered to this textbee account: id, name, enabled state, which one is the default sender, when each last checked in, and message counts. Call this when a send fails with a device error, when the user asks which phone will be used, or when you need a device_id. Takes no arguments and sends no SMS.
Inputs: no named parameters.
send_smsSend SMSA
Send an SMS through the user's own textbee account and Android phone. Recipients are phone numbers or short codes, sent as the user gives them. A local number or short code reaches recipients in the sending phone's country. For a number in another country, use international format with the country code, such as +15550100123. Sender names such as MYBANK cannot receive SMS. The sending phone is chosen automatically: the account default device, otherwise the enabled device with the most recent heartbeat. Only pass device_id when the user explicitly names a phone; ids come from list_devices. Sending costs the user a real message against their textbee plan quota, so do not send speculatively and do not retry a send that may already have gone out. When the account has SMS queueing enabled the result includes an sms_batch_id; pass it to get_messages as sms_batch_id to check per-recipient delivery status.
Inputs: message (required), recipients (required), device_id, sim_number, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool occupies a distinct role: send_sms writes, get_messages reads, list_devices enumerates devices. The descriptions explicitly clarify boundaries (e.g. list_devices sends no SMS, get_messages covers all devices without a device id), leaving no realistic chance of misselection.
All three names follow a consistent snake_case verb_noun pattern: send_sms, get_messages, list_devices. The verb choice (send/get/list) is semantically appropriate per tool rather than arbitrary, so the set reads predictably.
Three tools is exactly right for a narrow SMS gateway: send, read, and device discovery, with each tool earning its place. Nothing is padded and nothing feels thin given the constrained domain.
The core lifecycle is covered and cross-referenced well: sms_batch_id from send feeds get_messages, device_id from list_devices feeds send, and pagination/cursor rules prevent dead ends. Minor gaps remain (no account/quota info, no way to enable or disable a device when a send fails with a device error, no message deletion).
Maintenance
Related MCP Connectors
Send and read WhatsApp, email and SMS from Claude, ChatGPT, Cursor or any MCP client, from your own accounts: your WhatsApp number (linked by QR code), your mailbox (IMAP/SMTP) and your Android phone (SMS from its SIM). Tools: list-accounts, get-account, add-account, add-email-account, list-messages, send-message (one channel or several in one call). Hosted, OAuth 2.1, nothing to install. Free plan with unlimited messages; paid plans from 19 EUR/month remove the footer and add media and webhooks. Docs and client configs: github.com/UnlimitedMessaging/unlimited-messaging-mcp
SMS alerts for AI agents and scripts. Text your own phone and read replies. API key required.
Text your own phone from Claude and ChatGPT: reminders, alerts, scheduled SMS. Free 5 texts/mo.
Hosted two-way SMS bridge: your coding agent texts you when it needs an answer; you reply by SMS.
Related MCP Servers
- AlicenseBqualityDmaintenanceAndroidAPI.net MCP Connector lets Claude send SMS, WhatsApp messages, and OTPs via your linked Android device or gateway credits. Features * 52 tools covering SMS, WhatsApp, OTP, Contacts, Android devices * Works with Claude Desktop and Claude Code * Install: npx -y androidapi-mcp Setup Set ANDROIDAPI_SECRET env var with your API key from AndroidAPI.net → Tools → API Keys5239 npmMIT
- FlicenseNot gradedqualityCmaintenanceEnables Claude to read, organize, and send SMS messages through your ClickSend account.-
- FlicenseNot gradedqualityDmaintenanceEnables an AI-powered SMS assistant that receives inbound messages via TextBee, processes them with a local Ollama model and optional MCP tools, and sends replies back to the sender.1-
- FlicenseNot gradedqualityCmaintenanceEnables AI applications to send and receive real iMessage/SMS messages through a local MCP service, with tools for sending texts, checking new messages, browsing history, and querying line status.3-