# mailsocket

Supplies disposable email inboxes to coding agents and halts execution until a verification code or magic link lands in the inbox.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI
- Author: mailsocket
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/mailsocket/mailsocket-sdk/tree/HEAD/mcp
- Updated: 2026-10-20
- HTML: https://affpapa.org/en/nevibecode/mcp/mailsocket

## What it does

This integration provides agents with dedicated mailbox tools. An agent generates an address with `create_inbox`, then calls `wait_for_otp` or `wait_for_link`. The process pauses until matching mail arrives. The agent receives the extracted link or token without managing manual polling loops. The link is never followed.

Running the server requires Python 3.10 or newer when executing locally with `uvx mailsocket-mcp`. Supplying `MAILSOCKET_API_KEY` is mandatory: omitting it makes the process stop immediately with exit status 2. Alternatively, clients can point directly to the remote URL at `https://mcp.mailsocket.app/mcp`.

Remote calls cap the blocking duration at 55 seconds to prevent network proxies from dropping the connection. For sandbox validation, `send_test_code` injects sample authentication messages directly into an inbox. That tool is throttled to 5 messages per inbox and 20 per account each hour.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Remote server: `https://mcp.mailsocket.app/mcp`
- Environment variables: `MAILSOCKET_API_KEY`, `MAILSOCKET_BASE_URL` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

1. **Platform CLI**
```bash
claude mcp add --env MAILSOCKET_API_KEY=<MAILSOCKET_API_KEY> --env MAILSOCKET_BASE_URL=<MAILSOCKET_BASE_URL> --transport stdio mcp -- uvx mailsocket-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from mailsocket-mcp <command>

2. **Platform CLI: remote server**
```bash
claude mcp add --transport http mcp https://mcp.mailsocket.app/mcp
```

### Codex

1. **Platform CLI: remote server**
```bash
codex mcp add mcp --url https://mcp.mailsocket.app/mcp
```

2. **Platform CLI**
```bash
codex mcp add mcp --env MAILSOCKET_API_KEY=<MAILSOCKET_API_KEY> --env MAILSOCKET_BASE_URL=<MAILSOCKET_BASE_URL> -- uvx mailsocket-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from mailsocket-mcp <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "mcp": {
            "url": "https://mcp.mailsocket.app/mcp"
        }
    }
}
```
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "mcp": {
            "command": "uvx",
            "args": [
                "mailsocket-mcp"
            ],
            "env": {
                "MAILSOCKET_API_KEY": "<MAILSOCKET_API_KEY>",
                "MAILSOCKET_BASE_URL": "<MAILSOCKET_BASE_URL>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from mailsocket-mcp <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "mcp": {
            "type": "http",
            "url": "https://mcp.mailsocket.app/mcp"
        }
    }
}
```
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "mcp": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "mailsocket-mcp"
            ],
            "env": {
                "MAILSOCKET_API_KEY": "<MAILSOCKET_API_KEY>",
                "MAILSOCKET_BASE_URL": "<MAILSOCKET_BASE_URL>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from mailsocket-mcp <command>

### Gemini CLI

1. **Platform CLI: remote server**
```bash
gemini mcp add -t http mcp https://mcp.mailsocket.app/mcp
```

2. **Platform CLI**
```bash
gemini mcp add -e MAILSOCKET_API_KEY=<MAILSOCKET_API_KEY> -e MAILSOCKET_BASE_URL=<MAILSOCKET_BASE_URL> mcp uvx mailsocket-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from mailsocket-mcp <command>

## When to use it
- receive one-time verification passcodes during automated signups
- extract authentication magic links from incoming messages
- validate email receiving logic with simulated test codes
- provision throwaway inboxes without configuring mail infrastructure

## Example prompts
- Generate a new disposable address and wait for the verification passcode.
- Check for a magic login link sent to inbox `inbox_id`.
- Trigger a sample verification code to inbox `inbox_id` and read it back.

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 392262
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33989
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81163
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119231
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47577
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43902

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md