mailpit_mcp

mailpit_mcp

Model Context Protocol (MCP) server and HTTP client for Mailpit — local SMTP capture and inbox inspection for development and E2E testing.

Connects to a Mailpit instance on your machine (default http://127.0.0.1:8025). No cloud services, no stored credentials in this repository.

Requirements

• Node.js 20+
• A running Mailpit instance (Docker or binary)

Install

git clone https://github.com/exabyteso/mailpit_mcp.git
cd mailpit_mcp
npm install

Environment

Copy .env.example to .env locally (.env is gitignored). All configuration is optional:

| Variable | Default | Description | |----------|---------|-------------| | MAILPIT_URL | http://127.0.0.1:8025 | Mailpit HTTP API base URL | | MAILPIT_AUTH_USER | — | Basic auth username (if enabled on Mailpit) | | MAILPIT_AUTH_PASS | — | Basic auth password | | MAILPIT_TIMEOUT_MS | 30000 | HTTP request timeout |

Run the MCP server

npm start

Cursor / MCP client registration

Add to your workspace .cursor/mcp.json:

{
  "mcpServers": {
    "mailpit-local": {
      "command": "node",
      "args": ["src/index.mjs"],
      "cwd": "/absolute/path/to/mailpit_mcp",
      "env": {
        "MAILPIT_URL": "http://127.0.0.1:8025"
      }
    }
  }
}

When mailpit_mcp is cloned next to another project (sibling under Projects/), you can use a relative cwd from that project's workspace root.

MCP tools

| Tool | Description | |------|-------------| | mailpit_health | GET /api/v1/info | | mailpit_list_messages | Recent messages | | mailpit_search | Mailpit search query | | mailpit_get_message | Full message by ID | | mailpit_get_latest_for_recipient | Latest mail to an address | | mailpit_wait_for_message | Poll until a message matches | | mailpit_extract_otp | Parse verification code from body | | mailpit_delete_all | Clear mailbox (test reset) |

Programmatic client

import { createMailpitClient, extractOtp } from 'mailpit-mcp/client';

const mailpit = createMailpitClient();
await mailpit.deleteAll();

const message = await mailpit.waitForMessage({
  to: 'user@example.test',
  timeoutMs: 10_000,
});

const code = extractOtp(message.Text ?? '');

Tests

npm test

Unit tests use fixtures only — no live Mailpit required.

Security

See SECURITY.md. This repo ships no secrets. Configure auth via environment variables on your machine only.

License

MIT — see LICENSE.