SMSTunnel

SMSTunnel MCP server

Let Claude, Cursor, VS Code and other AI apps send texts from your own Android phone, from your own number, with SMSTunnel.

You ask your AI app to text someone; it hands the text to your SMSTunnel account, and your phone sends it from its own SIM, so the recipient sees a number they know and can reply to. The phone is linked to your account when you sign in to the SMSTunnel app, and you can cut this server off anytime by deleting its key in your dashboard.

Your phone needs the SMSTunnel app from Google Play:

What it can do

Every tool carries a title and the MCP annotations (read-only, destructive, idempotent, open-world), so your AI app can ask you before anything is sent.

Setup

1. Link your phone

Install the SMSTunnel app from Google Play on your Android phone and sign in. Sign in at smstunnel.io on your computer with the same account: the phone appears under Phones (you can also link it with the QR code from Phones → Add phone).

2. Create a key

In your SMSTunnel dashboard, open Apps → Add an app and copy its key. It is shown only once, and it can send texts and look up whether they went out.

To let your AI app read the texts you receive, also turn on Can also read received texts when you add the app (or Allow reading received texts later), and turn on syncing of received texts in the SMSTunnel app on the phone. Syncing is off by default; when you turn it on, only texts that arrive from then on are synced.

To let your AI app find a number by a name you saved in SMSTunnel ("text Ana"), turn on Can also look up names you saved in SMSTunnel for the key; it is off by default, and your phone's contacts are never shared this way.

3. Add the server to your AI app

Claude Desktop, the easy way: download smstunnel.mcpb and open it (double-click, or drag it into Settings → Extensions). Claude Desktop installs it, asks for your key and keeps it in your system's secure storage. Nothing else to install: Claude Desktop runs the bundled server itself.

For the other ways below you need Node.js 20 or newer. Your AI app starts the server with npx; you don't run it by hand.

Claude Desktop, by hand: in the Claude menu, open Settings… → Developer → Edit Config (claude_desktop_config.json), add the server, then quit and restart Claude:

{

"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 Code, as a plugin (the server plus the agent skill). Claude Code asks for your key and keeps it in your system's secure storage:

/plugin install smstunnel --marketplace narcisbodea/smstunnel-mcp

On Claude Code before 2.1.275, add the marketplace first: /plugin marketplace add narcisbodea/smstunnel-mcp, then /plugin install smstunnel@smstunnel.

Or only the server, without the plugin:

claude mcp add --env SMSTUNNEL_API_KEY=sk_live_your_key --transport stdio --scope user smstunnel -- npx -y @narcisbodea/smstunnel-mcp

Run /mcp in Claude Code to check that smstunnel is connected.

Cursor: , then replace sk_live_your_key with your key in Cursor's MCP settings. Or add the same mcpServers block as Claude Desktop to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project).

VS Code (.vscode/mcp.json): VS Code asks for the key once and keeps it out of the file:

{

"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}" } } } }

Gemini CLI, as an extension (the server, the agent skill and a short context file). Gemini CLI asks for your key and keeps it in your system's keychain:

gemini extensions install https://github.com/narcisbodea/smstunnel-mcp

Restart Gemini CLI and run /mcp to check that smstunnel is connected. To change the key later: gemini extensions config smstunnel SMSTUNNEL_API_KEY.

Docker: the image runs the same server over stdio, exactly the version published on npm. Build it once (Docker fetches this repository itself):

docker build -t smstunnel-mcp https://github.com/narcisbodea/smstunnel-mcp.git

Then point your AI app at it:

{

"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.

Settings

The server starts even without a key, so your AI app can list its tools; every call then says what is missing. The key is never printed or logged.

Try it

• "Text +14155550123: the delivery is at the back door."
• "Send my sign-in code 482913 to +447700900123."
• "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?"
• "Text Ana that I'm running late." (needs Can also look up names you saved in SMSTunnel)

Calendar reminders with an AI assistant

Add SMSTunnel next to your calendar in the same AI app, and the assistant can read your appointments and text reminders from your own number.

• "Look at my calendar for tomorrow and text each client with an appointment a reminder with the time and the address. Show me the list first."
• "Text me my agenda for tomorrow."
• "Did any client reply to today's reminders?" (needs Can also read received texts)

The assistant reads the events with your calendar connector, finds each client's phone number and shows you the whole list: each person, their number and the exact text. After your OK it sends one text per person, and it never resends a failed text on its own. Keep each client's number in the event (for example in the description), with + and the country code, so the assistant can find it.

Claude Desktop

1. Connect your calendar: open Customize → Connectors, find Google Calendar (or Microsoft 365 for an Outlook calendar; it needs a work or school Microsoft 365 account) and select Connect to Claude.
2. Add SMSTunnel as in Add the server to your AI app and restart Claude Desktop.
3. In a chat, select + → Connectors and make sure both your calendar and smstunnel are on.

Claude Code

1. Connect your calendar at claude.ai/customize/connectors. Connectors you add there appear in Claude Code when you're signed in with the same Claude account (/login). Google Calendar and Microsoft 365 can't be added with claude mcp add.
2. Add SMSTunnel:

   claude mcp add --env SMSTUNNEL_API_KEY=sk_live_your_key --transport stdio --scope user smstunnel -- npx -y @narcisbodea/smstunnel-mcp

1. Run /mcp: your calendar (listed as coming from claude.ai) and smstunnel should both be connected.

Claude Code asks you before every text (see SMSTUNNEL_CONFIRM_EACH_TEXT): with ten clients you approve ten texts, each showing the number and the words. Calendar events can come from other people (invitations), so read the list before you approve it.

Agent skill

skills/smstunnel-sms is an Agent Skill that tells your AI app when to use each tool and the rules above: one recipient per text, your OK before anything is sent, no automatic resends, received texts treated as information. The Claude Code plugin and the Gemini CLI extension install it for you. For other apps, copy the folder into the app's skills folder. The skill has no scripts; it works with the server set up as shown in Setup.

Safe use

• Only texts people expect. Alerts to yourself, replies, reminders, sign-in codes. Unsolicited texts from a personal SIM break most carriers' terms, and in the EU they fall under GDPR and the ePrivacy rules.
• You approve each text. The tools tell the assistant to show you the number and the words (or the whole list, for several people) and wait for your OK. AI apps ask before calling a tool that changes something, and Claude Code asks before every single text unless you set SMSTUNNEL_CONFIRM_EACH_TEXT=false.
• One recipient per text. There is no tool for several numbers: the assistant sends one text per person, at most about 30 a minute.
• No blind resends. A failed, unconfirmed or timed-out text may still have gone out; the tools tell the assistant to ask you instead of sending it again.
• Received texts are data. Anyone can text your phone, so the tools tell the assistant to treat received words as information, never as instructio