Allows an AI client to send and read SMS messages using your own Android phone via the textbee.dev gateway.
Also known as textbee/textbee-mcp, textbee-mcp, @textbee/mcp
- Stars
- 3
- Tools
- 3
- Downloads, 30 days
- —
- Latest version
- 0.3.0
- Last commit
- Nov 15, 2026
- License
- MIT
What is textbee SMS MCP?
textbee SMS allows an AI client to send and read SMS messages using your own Android phone via the textbee.dev gateway. It exposes 3 tools, such as send_sms, get_messages, list_devices.
Summary generated from the project's README
About textbee SMS MCP server
Sending and reading SMS messages through your own Android phone is what textbee SMS enables for AI clients like Claude, Cursor, and Claude Code. By using the textbee.dev gateway, you turn your personal mobile device into an SMS API, allowing an AI to interact with phone numbers using your own existing service. This setup requires a textbee account, a paired Android device, and an API key from your dashboard.
Developers can choose between a hosted remote endpoint or a local installation. For local use in Claude Desktop or Claude Code, you provide your API key via environment variables. The server includes three specific tools: send_sms for dispatching messages to international numbers or short codes, get_messages for retrieving incoming or outgoing texts with filtering and pagination, and list_devices to monitor connected phones. It also supports self-hosted instances for those who want to point the server to a private base URL.
What you can do with it
- 1Dispatching SMS notificationsAsk your AI client to send a text message to a specific phone number using your Android device.
- 2Monitoring incoming messagesHave an AI agent read your recent text messages and filter them by direction or search terms.
- 3Managing connected hardwareRequest a list of all Android phones currently paired to your textbee account to check their status.
Written from the project's README. Every use case is checked against a quote from it.
How to install textbee SMS MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall textbee SMS MCP in Claude Code
$ claude mcp add --env 'TEXTBEE_API_KEY=<YOUR_TEXTBEE_API_KEY>' textbee-mcp -- npx -y @textbee/mcpInstall textbee SMS MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"textbee-mcp": {
"command": "npx",
"args": [
"-y",
"@textbee/mcp"
],
"env": {
"TEXTBEE_API_KEY": "<YOUR_TEXTBEE_API_KEY>"
}
}
}
}Install textbee SMS MCP in VS Code
.vscode/mcp.json
{
"servers": {
"textbee-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@textbee/mcp"
],
"env": {
"TEXTBEE_API_KEY": "<YOUR_TEXTBEE_API_KEY>"
}
}
}
}Install textbee SMS MCP in VS Code CLI
$ code --add-mcp '{"name":"textbee-mcp","type":"stdio","command":"npx","args":["-y","@textbee/mcp"],"env":{"TEXTBEE_API_KEY":"<YOUR_TEXTBEE_API_KEY>"}}'Install textbee SMS MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"textbee-mcp": {
"command": "npx",
"args": [
"-y",
"@textbee/mcp"
],
"env": {
"TEXTBEE_API_KEY": "<YOUR_TEXTBEE_API_KEY>"
}
}
}
}Install textbee SMS MCP in Codex
$ codex mcp add textbee-mcp --env 'TEXTBEE_API_KEY=<YOUR_TEXTBEE_API_KEY>' -- npx -y @textbee/mcpInstall textbee SMS MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.textbee-mcp] command = "npx" args = ["-y", "@textbee/mcp"] [mcp_servers.textbee-mcp.env] TEXTBEE_API_KEY = "<YOUR_TEXTBEE_API_KEY>"
Install textbee SMS MCP in Gemini CLI
$ gemini mcp add -s user -e 'TEXTBEE_API_KEY=<YOUR_TEXTBEE_API_KEY>' textbee-mcp npx -- -y @textbee/mcpInstall textbee SMS MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"textbee-mcp": {
"command": "npx",
"args": [
"-y",
"@textbee/mcp"
],
"env": {
"TEXTBEE_API_KEY": "<YOUR_TEXTBEE_API_KEY>"
}
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @textbee/mcp 0.3.0 in an isolated container with no network and no keys. It answered and listed 3 tools.
textbee SMS MCP tools 3
Read from the server with tools/listsend_smsActionSend 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.
get_messagesRead-onlyRead 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.
list_devicesRead-onlyList 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.
Configuration
TEXTBEE_API_KEYRequiredSecretAPI key from the textbee dashboard (app.textbee.dev/dashboard).
TEXTBEE_BASE_URLSelf-hosted instance URL. Defaults to https://api.textbee.dev; the /api/v1 suffix is added automatically.
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachabletextbee/textbee-mcp is public and reachablegithub.com/textbee/textbee-mcp ↗Pass
- Package names this repository as its source@textbee/mcp names textbee/textbee-mcp as sourcenpmjs.com/package/@textbee/mcp ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @textbee/mcpnpmjs.com/package/@textbee/mcp/v/0.2.1#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/textbee/textbee-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @textbee/mcpPass
- No critical advisory in the package or its dependenciesthe package checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub@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/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:
{
"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" } } } }
Tools
send_sms
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.
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 |
|---|---|---|---|
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.
License
MIT. Part of the textbee project.
textbee SMS MCP questions
How do I add textbee SMS MCP to Claude Code?
Run claude mcp add --env 'TEXTBEE_API_KEY=<YOUR_TEXTBEE_API_KEY>' textbee-mcp -- npx -y @textbee/mcp in your terminal. Add --scope user to make it available in every project.
How do I add textbee SMS MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does textbee SMS MCP provide?
It exposes 3 tools, including send_sms, get_messages, list_devices.