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)

Related MCP server: MCP Mailtrap Server

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:

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

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.