Agents and automation

Connect AI agents and workflows to textbee: the MCP server for Claude and Cursor, a curl quickstart for any agent framework, and n8n for no-code flows.

Updated September 28, 2026

textbee gives AI agents and automation tools three ways to send and read SMS through your Android phone. Chat assistants such as Claude and Cursor use the MCP server. Any other agent framework calls two REST endpoints, and no-code builders use n8n.

All three paths use the same account, the same API key and the same plan limits. An agent cannot send more than your plan allows.

Which one to pick

You use	Pick	Why
Claude Desktop, Claude Code, Cursor or another MCP client	MCP server	The assistant gets `send_sms`, `get_messages` and `list_devices` as tools. No code.
claude.ai, the Claude mobile apps, or a client that cannot start a local process	MCP server, hosted endpoint	A hosted streamable HTTP endpoint with the same three tools
An agent framework, a script or an LLM that writes code	Agent quickstart	Two account-level endpoints: one to send, one to read
A workflow tool, without code	n8n	The HTTP Request node sends, the Webhook node receives
Node.js, Bun, Deno or Workers code	JavaScript SDK	Typed calls, a message iterator and webhook signature checks

MCP server for chat agents

The MCP server is the @textbee/mcp package on npm. You add it to your MCP client with your API key in an environment variable. The assistant can then send an SMS, read replies and list your phones inside a conversation.

This command adds the server to Claude Code:

Shell

claude mcp add textbee -s user -e TEXTBEE_API_KEY=your-key -- npx -y @textbee/mcp

Setup for Claude Desktop and Cursor, the tool parameters and the hosted endpoint are on the MCP server page. The source is at github.com/textbee/textbee-mcp.

REST quickstart for any agent

An agent needs two endpoints. Both are account-level, so the agent does not manage device ids.

Task	Endpoint
Send an SMS	`POST /gateway/send-sms`
Read messages, replies and delivery status	`GET /gateway/messages`

POST/api/v1/gateway/send-sms

This request sends one message:

Shell

curl -X POST https://api.textbee.dev/api/v1/gateway/send-sms \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"recipients": ["+12015550123"], "message": "Hello from textbee"}'

The agent quickstart shows how to check delivery with the smsBatchId and how to poll for replies with a cursor. Delivery status explains each message state. Message history lists every filter.

n8n for no-code workflows

n8n needs no community node. An HTTP Request node calls POST /gateway/send-sms with your API key in a header. A Webhook node receives the MESSAGE_RECEIVED event from a textbee webhook. See n8n for the node settings and common workflow patterns.

Rules for agents that send SMS

Confirm the recipient. Each recipient counts as one message against your plan. Ask the user before the agent texts a number the user did not give.
Do not retry a send that may have worked. A timeout does not mean the send failed. Check GET /gateway/messages with the smsBatchId or a search for the number first.
Do not retry a 429. A 429 means a plan limit is used up. A retry does not reset the limit.
Treat acceptance as acceptance. A 200 response means textbee accepted the message. The phone sends it after that.

Self-hosted instances

The MCP server and the SDK can talk to your own textbee instance. Set TEXTBEE_BASE_URL to your instance URL. See Self-hosting textbee.

Frequently asked questions

Does the agent need a device id?

No. When the send has no deviceId, textbee uses your default device, or else the enabled device with the most recent heartbeat. Pass a device id only to force a specific phone. See Devices.

Can the agent read replies?

Yes. get_messages in the MCP server and GET /gateway/messages in the API return received messages across all your phones. Turn on Receive SMS in the app first. See Receiving SMS.

Does reading messages use my plan quota?

No. Reads do not count against your message limits. Only sent and received messages count.