# textbee SMS MCP server

> Allows an AI client to send and read SMS messages using your own Android phone via the textbee.dev gateway.

- Repository: https://github.com/textbee/textbee-mcp
- Page: https://hostedmcp.org/servers/textbee/textbee-mcp
- Transport: stdio
- Stars: 3
- License: MIT
- Latest version: 0.3.0

## Install

### Claude Code

```sh
claude mcp add --env 'TEXTBEE_API_KEY=<YOUR_TEXTBEE_API_KEY>' textbee-mcp -- npx -y @textbee/mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "textbee-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@textbee/mcp"
      ],
      "env": {
        "TEXTBEE_API_KEY": "<YOUR_TEXTBEE_API_KEY>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "textbee-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@textbee/mcp"
      ],
      "env": {
        "TEXTBEE_API_KEY": "<YOUR_TEXTBEE_API_KEY>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"textbee-mcp","type":"stdio","command":"npx","args":["-y","@textbee/mcp"],"env":{"TEXTBEE_API_KEY":"<YOUR_TEXTBEE_API_KEY>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "textbee-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@textbee/mcp"
      ],
      "env": {
        "TEXTBEE_API_KEY": "<YOUR_TEXTBEE_API_KEY>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add textbee-mcp --env 'TEXTBEE_API_KEY=<YOUR_TEXTBEE_API_KEY>' -- npx -y @textbee/mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.textbee-mcp]
command = "npx"
args = ["-y", "@textbee/mcp"]

[mcp_servers.textbee-mcp.env]
TEXTBEE_API_KEY = "<YOUR_TEXTBEE_API_KEY>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'TEXTBEE_API_KEY=<YOUR_TEXTBEE_API_KEY>' textbee-mcp npx -- -y @textbee/mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "textbee-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@textbee/mcp"
      ],
      "env": {
        "TEXTBEE_API_KEY": "<YOUR_TEXTBEE_API_KEY>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `TEXTBEE_API_KEY` | yes | yes | API key from the textbee dashboard (app.textbee.dev/dashboard). |
| `TEXTBEE_BASE_URL` | no | no | Self-hosted instance URL. Defaults to https://api.textbee.dev; the /api/v1 suffix is added automatically. |

## Tools (3)

- `send_sms`: 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.
- `get_messages`: 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. (read-only)
- `list_devices`: 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. (read-only)
