SMSTunnel MCP server
Your AI assistant texts from your own phone, when you ask
“Text Ana that I'm running ten minutes late”
Ask your AI assistant to text someone, and it hands the text to your SMSTunnel account. Your own Android phone sends it from your own number, so the person sees a number they know and can reply. The assistant shows you the number and the words first, and sends one text per person.
What it can do
- send_sms
- Sends one text to one number. For several people, one text each.
- send_sign_in_code
- Sends a sign-in or verification code (a code of 4 to 10 digits).
- get_message_status
- Whether a text is pending, sent, delivered or failed.
- list_phones
- Your linked phones, and which are online.
- get_usage
- Your plan, what you sent today and what is left.
- list_received_texts
- Texts your phone received, only if you allow it.
1. Get your key
- 1. Install the SMSTunnel app from Google Play on your Android phone and sign in.
- 2. In your dashboard, open Apps → Add an app, pick AI assistants (MCP), name it (for example "AI assistant") and click Create the key.
- 3. Copy the key right away: it's shown only once. You can stop or delete the app there anytime, and AI assistant can't send texts anymore.
Get the steps with your key in them
It opens Add an app with AI assistants (MCP) picked. Once the key is made, the dashboard shows every step and command with the key already filled in, ready to copy.
To let the assistant read the texts you receive, also tick Can also read received texts and turn on syncing of received texts in the SMSTunnel app. It's off by default.
2. Add the server to your AI app
Claude Desktop, in one click
Download the SMSTunnel extension and open it. Claude Desktop installs it, asks for your key and keeps it in your system's secure storage. You don't need to install anything else.
Claude Code, as a plugin
The plugin adds the server and a skill that tells Claude how to text safely. Claude Code asks for your key once.
/plugin install smstunnel --marketplace narcisbodea/smstunnel-mcp Gemini CLI, as an extension
The extension adds the server and the same skill. Gemini CLI asks for your key, keeps it in your system's keychain, and also asks for an optional default country code.
gemini extensions install https://github.com/narcisbodea/smstunnel-mcp
Restart Gemini CLI and run /mcp to check that smstunnel is connected.
gemini extensions config smstunnel SMSTUNNEL_API_KEY Any app, by hand
You need Node.js 20
or newer. Your AI app starts the server with npx; you don't run it yourself.
{
"mcpServers": {
"smstunnel": {
"command": "npx",
"args": ["-y", "@narcisbodea/smstunnel-mcp"],
"env": {
"SMSTUNNEL_API_KEY": "sk_live_your_key"
}
}
}
}
On Windows, if the app can't start npx, use "command": "cmd" and
"args": ["/c", "npx", "-y", "@narcisbodea/smstunnel-mcp"].
claude mcp add --env SMSTUNNEL_API_KEY=sk_live_your_key --transport stdio --scope user smstunnel -- npx -y @narcisbodea/smstunnel-mcp {
"inputs": [
{ "type": "promptString", "id": "smstunnel-api-key", "description": "SMSTunnel API key", "password": true }
],
"servers": {
"smstunnel": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@narcisbodea/smstunnel-mcp"],
"env": { "SMSTUNNEL_API_KEY": "${input:smstunnel-api-key}" }
}
}
} In Docker
No Node.js on your computer? The image runs the same server over stdio, exactly the version published on npm. Build it once (Docker fetches the repository itself):
docker build -t smstunnel-mcp https://github.com/narcisbodea/smstunnel-mcp.git Then point your AI app at it, in the same place as the block above:
{
"mcpServers": {
"smstunnel": {
"command": "docker",
"args": ["run", "-i", "--rm", "-e", "SMSTUNNEL_API_KEY", "smstunnel-mcp"],
"env": { "SMSTUNNEL_API_KEY": "sk_live_your_key" }
}
}
}
The container runs as an unprivileged user and needs no ports or volumes. -e SMSTUNNEL_API_KEY
hands it the key from env without putting the key on the command line; pass the other settings
below the same way.
- SMSTUNNEL_API_KEY
- Required: the key from Apps → Add an app.
- SMSTUNNEL_DEVICE_ID
- Optional: the phone that sends (its ID is under Phones).
- SMSTUNNEL_DEFAULT_COUNTRY_CODE
- Optional, like +44: completes numbers written without + or 00.
- SMSTUNNEL_CONFIRM_EACH_TEXT
- true by default: apps that support it, like Claude Code, ask before every text.
Try it
- "Text +14155550123: the delivery is at the back door."
- "Did my last text go out?"
- "Which of my phones are online?"
- "How many texts do I have left today?"
- "Did anyone reply to me since this morning?" (with received texts allowed)
Calendar reminders with your assistant
Turn on a calendar connector next to SMSTunnel (in Claude: Customize → Connectors, Google Calendar,
or Microsoft 365 for a work or school Outlook calendar). Then ask: "Look at my calendar for tomorrow and text each
client with an appointment a reminder with the time. Show me the list first." Keep each client's number in the event,
with + and the country code.
The assistant acts when you ask; it doesn't run on a schedule. For reminders that go out on their own, see Google Calendar reminders or Outlook Calendar reminders.
Safe use
- You approve each text. The assistant shows the number and the words (or the whole list) and waits for your OK.
- One recipient per text. There is no tool for several numbers: one text per person, about 30 a minute at most.
- Only texts people expect. Replies, reminders, alerts to yourself, sign-in codes.
- No blind resends. A failed or unconfirmed text may still have gone out; the assistant asks you instead of sending it again.
- Received texts are data. Anyone can text your phone, so the assistant treats their words as information, never as instructions.
- Your key stays in your AI app's settings, never in a chat. Delete the app under Apps to cut it off.
ChatGPT? ChatGPT connects only to MCP servers on the internet, over HTTPS, so it can't start this server on your computer. Use Claude Desktop, Claude Code, Cursor, VS Code or Gemini CLI.
Build it with an AI assistant
Copy this prompt into Claude, ChatGPT, Cursor or Copilot and replace the part in [brackets]. Don't paste your API key into the chat: the prompt doesn't need it.
Help me connect the SMSTunnel MCP server to my AI app, so it can send texts from my own phone when I ask.
About SMSTunnel (https://smstunnel.io): my own apps and tools hand text messages (SMS) to my SMSTunnel account, and my own Android phone sends them from my own number, on my own SIM and plan. The phone runs the SMSTunnel app from Google Play (https://play.google.com/store/apps/details?id=io.smstunnel.app), signed in to my account.
What I want: [describe what should send a text, to whom, and when]
How it works:
- MCP server: my AI app starts it with "npx -y @narcisbodea/smstunnel-mcp" (Node.js 20+, stdio). Settings in the server's "env": SMSTUNNEL_API_KEY (required), SMSTUNNEL_DEVICE_ID, SMSTUNNEL_DEFAULT_COUNTRY_CODE, SMSTUNNEL_CONFIRM_EACH_TEXT (true by default: apps that support it ask before every text).
- Claude Desktop (Settings → Developer → Edit Config, claude_desktop_config.json) and Cursor (~/.cursor/mcp.json or .cursor/mcp.json):
{
"mcpServers": {
"smstunnel": {
"command": "npx",
"args": ["-y", "@narcisbodea/smstunnel-mcp"],
"env": {
"SMSTUNNEL_API_KEY": "sk_live_your_key"
}
}
}
}
- Claude Desktop, easiest: download https://github.com/narcisbodea/smstunnel-mcp/releases/latest/download/smstunnel.mcpb and open it; Claude Desktop asks for the key.
- Claude Code, easiest: /plugin install smstunnel --marketplace narcisbodea/smstunnel-mcp (the server plus a skill; Claude Code asks for the key). Without the plugin: claude mcp add --env SMSTUNNEL_API_KEY=sk_live_your_key --transport stdio --scope user smstunnel -- npx -y @narcisbodea/smstunnel-mcp
- Gemini CLI: gemini extensions install https://github.com/narcisbodea/smstunnel-mcp (the server plus the skill; Gemini CLI asks for the key and keeps it in the system keychain; change it later with gemini extensions config smstunnel SMSTUNNEL_API_KEY). Restart Gemini CLI and run /mcp to check.
- VS Code (.vscode/mcp.json; VS Code asks for the key once):
{
"inputs": [
{ "type": "promptString", "id": "smstunnel-api-key", "description": "SMSTunnel API key", "password": true }
],
"servers": {
"smstunnel": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@narcisbodea/smstunnel-mcp"],
"env": { "SMSTUNNEL_API_KEY": "${input:smstunnel-api-key}" }
}
}
}
- Docker, without Node.js on the computer: build the image once with docker build -t smstunnel-mcp https://github.com/narcisbodea/smstunnel-mcp.git (it runs the version published on npm), then use this config; each setting goes in "env" and as "-e", "<NAME>" in "args":
{
"mcpServers": {
"smstunnel": {
"command": "docker",
"args": ["run", "-i", "--rm", "-e", "SMSTUNNEL_API_KEY", "smstunnel-mcp"],
"env": { "SMSTUNNEL_API_KEY": "sk_live_your_key" }
}
}
}
- Tools: send_sms (to, message, deviceId?, defaultCountryCode?), send_sign_in_code (a code of 4 to 10 digits), get_message_status (messageId), list_phones, get_usage, list_received_texts (only if the key may read received texts and the phone syncs them).
- ChatGPT only connects to remote MCP servers over HTTPS, so it can't start this local server.
- One recipient per request: SMSTunnel sends one text to one number. For several people, one request (or one notification) per number.
- Answers: 200 {"success": true, "messageId": "…"}; 401 wrong or deleted key; 403 the key lacks a permission ("code": "PERMISSION_REQUIRED"); 400 a missing, unknown or too long field; 429 too many requests (30 sends a minute, with Retry-After): wait and retry; without Retry-After, the plan's limit for the day or month is reached. If my phone is offline the text waits and goes out when it is back, within 3 days.
- The API key comes from my SMSTunnel dashboard (https://dashboard.smstunnel.io): Apps → Add an app → Create the key. It is shown only once and can send texts and check whether they went out.
Rules for your answer:
- Do not ask for my SMSTunnel password or API key and do not put a real key in your answer; I will not paste it in this chat.
- Phone numbers must be in international format (+ and the country code).
- Help me test it with my own number first.
- Only send texts people expect from me. No unsolicited texts.
- Always show me the number and the words before a text is sent, and never resend a text on your own. Responsible use
Built for alerts to yourself and your team, and texts people expect from you. One text goes to one number. Sending unsolicited messages from a consumer SIM generally breaches mobile carrier terms of service.
Claude, Cursor, Visual Studio Code, Gemini and Docker are trademarks of their owners. SMSTunnel is a third-party integration and is not affiliated with, endorsed by, or sponsored by Anthropic, Anysphere, Microsoft, Google or Docker.