@koderlabs/inbox-mcp

A Model Context Protocol (MCP) server that provides disposable email inboxes for end-to-end testing, powered by InstantInbox.

Lets AI coding agents (Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, etc.) create temporary email addresses on demand and read messages received at them. Useful for testing any email-driven flow: signup verification, password reset, magic links, OTP codes, transactional notifications.

Key Features

• Disposable inboxes on demand — agents create real *@inbox.koderlabs.net addresses in a single tool call.
• Long-poll for delivery — wait_for_email blocks until a matching email arrives (up to 120s), so agents do not need to retry.
• Structured email payloads — text, HTML, headers, and parsed metadata returned as typed JSON.
• Two transports — stdio (local launch via npx) and Streamable HTTP (hosted, OAuth in browser).
• Scoped tokens — fine-grained API keys (inbox:read, email:write, etc.) gate every tool.

Requirements

• Node.js 18+
• An InstantInbox account (sign up free)
• Any MCP-compatible client (Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Goose, etc.)

Getting Started

Standard Configuration

Most clients use the same npx-based command:

{
  "mcpServers": {
    "instantinbox": {
      "command": "npx",
      "args": ["-y", "@koderlabs/inbox-mcp"],
      "env": {
        "INBOX_API_KEY": "<your token>"
      }
    }
  }
}

Or use the hosted HTTP transport (no token in config — OAuth in browser):

https://inbox.koderlabs.net/mcp

Install in Claude Code

Hosted (recommended — OAuth in browser, no API key in files):

claude mcp add --transport http instantinbox https://inbox.koderlabs.net/mcp

Stdio (API key):

claude mcp add instantinbox \
  -e INBOX_API_KEY=<your token> \
  -- npx -y @koderlabs/inbox-mcp

Install in Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows) and add the standard configuration above. Restart Claude Desktop.

Install in Cursor

Settings → MCP Servers → Add Server

• Command: npx
• Args: -y @koderlabs/inbox-mcp
• Env: INBOX_API_KEY=<your token>

Or paste the standard JSON into ~/.cursor/mcp.json.

Install in VS Code / VS Code Insiders

Add to .vscode/mcp.json (workspace) or User Settings → MCP:

{
  "servers": {
    "instantinbox": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@koderlabs/inbox-mcp"],
      "env": { "INBOX_API_KEY": "<your token>" }
    }
  }
}

Install in Windsurf

Add the standard configuration to ~/.codeium/windsurf/mcp_config.json. See Windsurf MCP docs for details.

Install in Gemini CLI

Add the standard configuration block to ~/.gemini/settings.json under mcpServers.

Install in Goose

Settings → Extensions → Add custom extension, select STDIO, command npx -y @koderlabs/inbox-mcp, env INBOX_API_KEY=<your token>.

Install in LM Studio

Edit mcp.json in LM Studio settings and add the standard configuration block.

Install in Cline

Edit cline_mcp_settings.json and add the standard configuration block.

Install in Copilot (GitHub Copilot Chat)

Add the standard configuration to your .vscode/mcp.json — Copilot Chat in VS Code reuses VS Code's MCP config.

Getting a token

1. Sign up at inbox.koderlabs.net.
2. Generate an API key at Settings → API Keys with the scopes you need.
3. Restart your MCP client after editing config.

Configuration

Environment Variables

| Variable | Default | Purpose | |---|---|---| | INBOX_API_KEY | — | Required for stdio. Bearer token for the InstantInbox API | | INBOX_API_BASE_URL | https://inbox.koderlabs.net/api/v1 | API base — override only if self-hosting | | PORT | 10405 | Port for the Streamable HTTP transport (self-hosted only) |

Scopes

API keys carry scopes; each tool checks for one:

| Scope | Grants | |---|---| | inbox:read | List / get inboxes | | inbox:write | Create / delete inboxes | | email:read | List / get emails, wait_for_email | | email:write | Delete emails, mark read/unread |

The server returns a structured error if a tool is called without the required scope.

Standalone MCP Server (HTTP transport)

The package ships a Streamable-HTTP transport for self-hosted deployments. Start it with:

INBOX_API_BASE_URL=https://your-host/api/v1 \
PORT=10405 \
npx @koderlabs/inbox-mcp --http

Then point your client at http://your-host:10405/mcp. The hosted instance at https://inbox.koderlabs.net/mcp uses OAuth — clients open a browser tab on first connect.

Security

@koderlabs/inbox-mcp is not a security boundary. Treat any inbox created through it as public — emails are accepted from the open internet at *@inbox.koderlabs.net and are visible to anyone with the inbox address and a valid scoped token.

• Use a dedicated API key per agent / project; revoke from the dashboard if leaked.
• Emails auto-purge after 24h (EMAIL_RETENTION_HOURS on self-hosted).
• Do not route production-sensitive mail (password resets for real user accounts, financial codes, etc.) through this service.

See MCP Security Best Practices for general guidance.

Tools Reference

Identity

| Tool | Purpose | |---|---| | whoami | Show identity + granted scopes |

Inboxes (requires inbox:read / inbox:write)

| Tool | Purpose | |---|---| | list_inboxes | List your inboxes | | create_inbox | Create a disposable inbox. Returns full address (e.g. [email protected]) | | get_inbox | Look up by id or address | | delete_inbox | Permanently delete an inbox |

Emails (requires email:read / email:write)

| Tool | Purpose | |---|---| | list_emails | List emails in an inbox (headers only) | | get_email | Fetch one email's full body (text + html + headers) | | wait_for_email | Long-poll until a matching email arrives (up to 120s). Filter by subjectContains, fromContains | | delete_email | Delete one email | | mark_email_read | Mark email read / unread |

wait_for_email is the workhorse — most email tests are trigger → wait → extract → click.

Example Agent Prompts

Create a disposable inbox, sign up at https://example.com using that address, then read the verification email and click the link.

Test the password-reset flow on staging: create an inbox, request reset, wait for the email, extract the reset token, and confirm reset works with a new password.

Spin up 5 disposable inboxes and trigger our newsletter signup with each — verify the welcome email arrives within 30 seconds.

Links

• Service: inbox.koderlabs.net
• Source: github.com/jawaidgadiwala/instant-inbox
• Issues: github.com/jawaidgadiwala/instant-inbox/issues

License

MIT