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.