mailpit_mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mailpit_mcp get latest email for user@example.test"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 installEnvironment
Copy .env.example to .env locally (.env is gitignored). All configuration is optional:
Variable | Default | Description |
|
| Mailpit HTTP API base URL |
| — | Basic auth username (if enabled on Mailpit) |
| — | Basic auth password |
|
| HTTP request timeout |
Run the MCP server
npm startCursor / 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 |
|
|
| Recent messages |
| Mailpit search query |
| Full message by ID |
| Latest mail to an address |
| Poll until a message matches |
| Parse verification code from body |
| 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 testUnit 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 toolsmailpit_delete_allADestructive
Delete all messages in the Mailpit mailbox (test reset)
Inputs: no named parameters.
mailpit_extract_otpARead-only
Extract a numeric verification code from message plain text or HTML
Inputs: text, message_id.
mailpit_get_latest_for_recipientBRead-only
Get the most recent message sent to a recipient email address
Inputs: recipient (required).
mailpit_get_messageARead-only
Get full message content by ID (or "latest")
Inputs: id (required).
mailpit_healthARead-only
Check Mailpit server health via GET /api/v1/info
Inputs: no named parameters.
mailpit_list_messagesBRead-only
List recent captured messages (newest first)
Inputs: start, limit.
mailpit_searchARead-only
Search messages using Mailpit query syntax (e.g. to:user@example.test subject:welcome)
Inputs: query (required), limit.
mailpit_wait_for_messageBRead-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
Scored across 8 tools
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.
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.
8 tools is well-scoped for an email testing server. Each tool serves a necessary function without being excessive or insufficient.
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
Related MCP Connectors
Disposable test mailboxes on a real domain: send, receive and assert on real email.
Capture, inspect, send and assert on webhooks and inbound email from your coding agent.
Test-inbox API for email and SMS: create inboxes, long-poll messages, extract OTPs and links.
MCP server for e-mail testing: create disposable inboxes, wait for delivery, and extract e-mail content or links - all from your AI agent or test automation workflow. Get a free API key on https://app.zyntra.app/
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables interaction with Mailosaur email and SMS testing services, allowing message management, server configuration, file downloads, spam analysis, and TOTP code retrieval via natural language.29MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to read, search, and manage emails from Mailpit, an email and SMTP testing tool, during development and testing.MIT
- FlicenseAqualityDmaintenanceProvides a dummy SMTP server for catching emails during development, with MCP tools to list, retrieve, and manage received messages.4-
- AlicenseNot gradedqualityDmaintenanceProvides 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.2MIT