simrelay-mcp-server

Sign in to SimRelay via OAuth. Opens the user's default browser to the SimRelay authorization page; after they authorize, tokens are saved locally and refreshed automatically. Returns the path where tokens were stored. Call this when the user asks to log in or when another tool fails with 'Not authenticated'.

Forget the saved SimRelay OAuth tokens. Idempotent — safe to call even when not signed in. After this, the next tool call that needs auth will require simrelay_login again.

List all SIMs the authenticated user can access, grouped by team. Each SIM includes id, phone_number, status, alias (organization-pivot label), organization, type, messages_received_count, and current lock state (unlocked, or locked-by-user with expiry). The response is structured as `groups: [{ team, sims: [...] }, ...]` plus a top-level flat `sims` array for convenience.

Acquire an exclusive lock on a SIM so other users/agents cannot send or read messages on it. Locks expire automatically after the server-configured TTL (typically a few minutes). Use the integer hosted_sim_id from list_sims.

Release a previously acquired lock on a SIM. Idempotent — safe to call even if the lock has already expired or never existed.

Retrieve historical SMS messages for a SIM, paginated. Returns a normalized list (id, sim_id, direction, from, to, text, received_at) plus pagination metadata.

Open (or reuse) a WebSocket subscription that streams new SMS for the authenticated user. Each incoming SMS is pushed as an MCP `notifications/message` (logger=simrelay-sms, level=info, JSON-encoded payload). Also kept in an internal ring buffer of the most recent 100. Pass sim_id to filter to a single SIM. Idempotent — calling again updates the filter and returns the current subscription state.

Block until the next SMS arrives (optionally filtered by sim_id) and return its payload. Use this when an agent expects a code/OTP imminently — the call returns synchronously with the message so you don't have to poll. Ensures a WebSocket subscription is open before waiting; reuses any existing one. Default timeout is 60s, max 300s. Throws after the timeout if no matching SMS arrives.

Return the N most-recent SMS messages captured by the WebSocket subscription in this server's lifetime (in-memory ring buffer, capacity 100). Filter by sim_id if provided. Returns an empty list if the subscription was never started or no matching SMS has arrived since startup. For historical messages persisted by SimRelay, use get_sim_messages instead.

Return the current WebSocket subscription state, the channel we're listening on, the active filter, and the most recent buffered SMS events. Useful for diagnosing why messages aren't arriving.

Stop the real-time SMS stream and close the WebSocket. Idempotent — safe to call even if no subscription is active.