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
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.ai, Claude Desktop, the Claude mobile apps or Claude Code | MCP server, hosted connector | Add a custom connector and sign in with your API key. Nothing to install. |
| Cursor or another MCP client | MCP server, local | The assistant gets send_sms, get_messages and list_devices as tools. No code. |
| 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 gives a chat assistant three tools. The assistant can then send an SMS, read replies and list your phones inside a conversation. You connect it in one of two ways:
- Hosted connector. In claude.ai or Claude Desktop, open Customize, then Connectors, then + Add and Add custom connector. Enter the URL
https://mcp.textbee.dev/mcp, click Continue, then Add, and paste your API key on the textbee sign-in page. It works on the web, in Claude Desktop and in the Claude mobile apps. - Local server. The
@textbee/mcppackage on npm runs on your machine with your API key in an environment variable.
This command adds the hosted connector to Claude Code. Run /mcp and choose Authenticate after it:
claude mcp add --transport http -s user textbee https://mcp.textbee.dev/mcpThis command adds the local server to Claude Code instead:
claude mcp add textbee -s user -e TEXTBEE_API_KEY=your-key -- npx -y @textbee/mcpSetup for Claude Desktop and Cursor, the tool parameters and the hosted endpoint details 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 |
/api/v1/gateway/send-sms, open in the API reference
This request sends one message:
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/messageswith thesmsBatchIdor asearchfor 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.