MCP server for SMS

If you're running an agent inside Claude Desktop, Claude Code, Cursor, or any other Model Context Protocol-aware host, the SIMRelay MCP server is the cleanest way to give that agent a phone number. Instead of writing a custom HTTP client, you connect the MCP server and SMS becomes a set of tools the agent can call natively.

Source on GitHub: github.com/simrelay/mcp · npm package: simrelay-mcp-server (ISC-licensed).

What MCP is, briefly

The Model Context Protocol (MCP) is an open standard for exposing tools, resources, and prompts to LLM hosts. Anthropic introduced it, and it's now supported by Claude Desktop, Claude Code, Cursor, and a growing list of other hosts. Tools registered via MCP appear in the agent's tool palette and can be invoked the same way the agent invokes any other tool.

What the SIMRelay MCP server exposes

  • simrelay_login — open the browser to sign in to SimRelay (OAuth, run on first use).
  • simrelay_logout — forget saved tokens.
  • list_sims — list every SIM the user can access (id, phone number, status, country, provider, lock state).
  • lock_sim — acquire an exclusive lock on a SIM by hosted_sim_id.
  • release_sim_lock — release a lock; idempotent.
  • get_sim_messages — paginated SMS history for a SIM (page, per_page up to 100).
  • subscribe_to_messages — open a WebSocket subscription; new SMS are pushed to the MCP client as notifications/message events.
  • unsubscribe_from_messages — stop the WebSocket subscription.

Setup

There are two install paths. For Claude Desktop we recommend the bundled .mcpb extension from the GitHub releases — drop it in and you're done. For Claude Code, Cursor, or any generic MCP host, install the npm package:

npm install -g simrelay-mcp-server

For Claude Code:

claude mcp add simrelay -- simrelay-mcp

For a generic MCP client, register an stdio server with command simrelay-mcp.

Sign-in is OAuth, not API keys

The first time the agent calls a SimRelay tool, the server triggers simrelay_login, which opens your browser. Sign in once; refresh tokens persist to ~/.config/simrelay-mcp/tokens.json (chmod 0600) and renew automatically. Credentials never travel through tool arguments. You can also run simrelay-mcp login in a terminal beforehand.

Real-time SMS streaming

After the agent calls subscribe_to_messages, each new SMS is pushed to the MCP client as a structured logging notification (logger simrelay-sms) with payload like { event: "sms.received", sim_id, from, text, received_at, raw }. In Claude Desktop these surface inline in the conversation, so the agent can react within the same session — extract an OTP and submit it, for example.

When to use MCP vs the API

Use MCP when your agent runs inside an MCP-aware host and you want SMS to be a first-class tool the model can reason about. Use the HTTP API when you're running your own agent loop (e.g., a custom OpenAI Agents or LangGraph runtime) and you'd rather call SIMRelay directly. Both end up at the same underlying data — pick whichever matches your runtime.