Skip to main content
Glama
mailpit_mcp

mailpit_mcp

by exabyteso

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: mailpit-mcp-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:

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.

Available Tools

8 tools
mailpit_delete_allA
Destructive

Delete all messages in the Mailpit mailbox (test reset)

Inputs: no named parameters.

mailpit_extract_otpA
Read-only

Extract a numeric verification code from message plain text or HTML

Inputs: text, message_id.

mailpit_get_latest_for_recipientB
Read-only

Get the most recent message sent to a recipient email address

Inputs: recipient (required).

mailpit_get_messageA
Read-only

Get full message content by ID (or "latest")

Inputs: id (required).

mailpit_healthA
Read-only

Check Mailpit server health via GET /api/v1/info

Inputs: no named parameters.

mailpit_list_messagesB
Read-only

List recent captured messages (newest first)

Inputs: start, limit.

mailpit_wait_for_messageB
Read-only

Poll Mailpit until a matching message arrives or timeout

Inputs: to, from, subject_contains, query, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: delete all, extract OTP, get latest for recipient, get by ID, health check, list, search, and wait. No overlap or ambiguity.

    Naming Consistency4/5

    All tools start with 'mailpit_' and most follow a verb_noun pattern (e.g., mailpit_delete_all, mailpit_list_messages). However, 'mailpit_health' is a noun only and 'mailpit_search' is a verb without a noun, causing slight inconsistency.

    Tool Count5/5

    8 tools is well-scoped for an email testing server. Each tool serves a necessary function without being excessive or insufficient.

    Completeness5/5

    The tool set covers all essential operations for Mailpit: health check, listing, retrieving, searching, waiting, extracting OTPs, and resetting the mailbox. No obvious gaps for the intended domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables interaction with Mailosaur email and SMS testing services, allowing message management, server configuration, file downloads, spam analysis, and TOTP code retrieval via natural language.
      29
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides MCP tools to manage MailDev Docker containers and inspect received emails, including listing, searching, retrieving, deleting, waiting for, and verifying email content and attachments for local development and test automation.
      2
      MIT