Skip to main content
Glama
textbee-mcp

textbee-mcp

Official
README.md
# @textbee/mcp

[![npm version](https://img.shields.io/npm/v/%40textbee%2Fmcp)](https://www.npmjs.com/package/@textbee/mcp)
[![CI](https://github.com/textbee/textbee-mcp/actions/workflows/ci.yaml/badge.svg)](https://github.com/textbee/textbee-mcp/actions/workflows/ci.yaml)
[![license](https://img.shields.io/npm/l/%40textbee%2Fmcp)](./LICENSE)

MCP server for [textbee.dev](https://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](https://app.textbee.dev/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.

1. In claude.ai or Claude Desktop, open **Customize**, then **Connectors**, then **+ Add** and **Add custom connector**.
2. Enter the name `textbee` and the URL `https://mcp.textbee.dev/mcp`, then click **Continue** twice.
3. Choose **Sign in now**, leave the OAuth client on the recommended option, and click **Add**.
4. 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:

```bash
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:

```bash
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:

```json
{
  "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](https://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:

```bash
npm install -g @textbee/mcp
```

```json
{ "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. 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:

```json
"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):

```js
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](https://github.com/textbee/textbee) project.

TDQS

A4.7/5.0

Scored across 3 tools

Disambiguation5/5

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.

Naming Consistency5/5

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.

Tool Count5/5

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.

Completeness4/5

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

ActivityNo data
ResponsivenessOutdated data