mailsocket — MCP server

An MCP server that exposes mailsocket to AI coding agents as native tools, so an agent can create a throwaway inbox and block on the OTP or magic link without writing any polling code. It wraps the Python SDK — no second HTTP client, no re-implemented polling.

What it does

Errors from the SDK (AuthError / NotFound / RateLimited / WaitTimeout) are turned into clean MCP tool errors — no stack traces, and the API key is never echoed back.

Requirements

• Python 3.10+
• A mailsocket API key — from the dashboard or POST /api/v1/agents/register.

Install

No install needed with uv:

uvx mailsocket-mcp

Or install with pip:

pip install mailsocket-mcp
mailsocket-mcp

Either way, it reads MAILSOCKET_API_KEY (and optional MAILSOCKET_BASE_URL) from the environment. If the key is missing it exits with a clear message and status 2; the key is never logged.

Register with an MCP client

Claude Desktop / Cursor

Add this to your client's MCP config file — claude_desktop_config.json for Claude Desktop, ~/.cursor/mcp.json for Cursor:

{
  "mcpServers": {
    "mailsocket": {
      "command": "uvx",
      "args": ["mailsocket-mcp"],
      "env": {
        "MAILSOCKET_API_KEY": "ms_live_..."
      }
    }
  }
}

Claude Code CLI

claude mcp add mailsocket -e MAILSOCKET_API_KEY=ms_live_... -- uvx mailsocket-mcp

Any other MCP-compatible client works the same way: point it at the mailsocket-mcp executable (or uvx mailsocket-mcp) over stdio and pass the key through the environment.

Env vars

Develop

pip install -e ".[dev]"
pytest

Tests are fully offline — the SDK client is faked, so nothing touches the live API.