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.

Install

# from this directory, with the repo's backend venv (or your own):
/Users/tuki/MailBridge/backend/.venv/bin/python -m pip install mcp          # official MCP SDK
/Users/tuki/MailBridge/backend/.venv/bin/python -m pip install -e ../python # local mailsocket SDK
/Users/tuki/MailBridge/backend/.venv/bin/python -m pip install -e .         # this server (mailsocket-mcp)

Run

export MAILSOCKET_API_KEY="ms_live_..."
# optional: export MAILSOCKET_BASE_URL="https://dash.mailsocket.app/api/v1"
mailsocket-mcp

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

The server is a plain stdio MCP server, so it works with any MCP-compatible client. Point your client's mcpServers config at the mailsocket-mcp executable and pass the key through the environment:

{
  "mcpServers": {
    "mailsocket": {
      "command": "mailsocket-mcp",
      "args": [],
      "env": {
        "MAILSOCKET_API_KEY": "ms_live_...",
        "MAILSOCKET_BASE_URL": "https://dash.mailsocket.app/api/v1"
      }
    }
  }
}

If mailsocket-mcp is not on the client's PATH, use the venv's full path for command, e.g. /Users/tuki/MailBridge/backend/.venv/bin/mailsocket-mcp.

Develop

cd sdks/mcp
/Users/tuki/MailBridge/backend/.venv/bin/python -m pytest -q

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