Send and read SMS through your own Android phone via textbee.dev, the open-source SMS gateway.
# @textbee/mcp
[](https://www.npmjs.com/package/@textbee/mcp)
[](https://github.com/textbee/textbee-mcp/actions/workflows/ci.yaml)
[](https://www.npmjs.com/package/@textbee/mcp)
[](https://github.com/textbee/textbee-mcp/actions/workflows/ci.yaml)
[
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.
Key features
01. Send and read SMS through your own Android phone via textbee
Enter the name textbee and the URL https://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/mcp
Or hosted, signing in with your key in the browser:
claude mcp add --transport http -s user textbee https://mcp.textbee.dev/mcp
Then 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:
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>.
Send an SMS to one or more phone numbers or short codes. International format with the country code (for example +15550100123) works everywhere. Local numbers and short codes only reach recipients in the sending phone's country. The sending phone is chosen automatically: your default device, otherwise the enabled device with the most recent heartbeat. Optional device_id, sim_subscription_id, and scheduled_at. 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.
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
TEXTBEE_API_KEY
yes
none
API key from the textbee dashboard
TEXTBEE_BASE_URL
no
https://api.textbee.dev
Your instance's URL when self-hosting
TEXTBEE_TIMEOUT_MS
no
30000
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.
