Mailpit MCP Server
A standalone Model Context Protocol (MCP) server that enables AI assistants to interact with Mailpit email testing environments.
Overview
This project provides an MCP server that connects AI assistants (Claude, Cursor, VS Code Copilot, etc.) to Mailpit's API, enabling natural language interaction with your email testing workflow.
Key Features:
- Browse, search, and analyze emails using natural language
- Check HTML compatibility across email clients
- Validate links and detect broken images
- Run spam analysis on messages (requires SpamAssassin)
- Send test emails and manage tags
- Debug email delivery issues
Prerequisites
- A running Mailpit instance (the MCP server connects to Mailpit via its HTTP API)
- Go 1.24+ (if building from source)
Installation
Option 1: Docker (Recommended)
docker run -d \
--name mailpit-mcp \
-e MAILPIT_URL=http://your-mailpit-host:8025 \
-e MCP_TRANSPORT=http \
-p 3000:3000 \
ghcr.io/amirhmoradi/mailpit-mcp:latest
Option 2: Docker Compose
Create a docker-compose.yml:
services:
mailpit:
image: axllent/mailpit:latest
ports:
- "8025:8025"
- "1025:1025"
mailpit-mcp:
image: ghcr.io/amirhmoradi/mailpit-mcp:latest
environment:
MAILPIT_URL: http://mailpit:8025
MCP_TRANSPORT: http
ports:
- "3000:3000"
depends_on:
- mailpit
Run with:
docker-compose up -d
Option 3: Build from Source
# Clone the repository
git clone https://github.com/amirhmoradi/mailpit-mcp.git
cd mailpit-mcp
# Build the binary
cd mcp
go build -o mailpit-mcp-server ./cmd/mailpit-mcp-server
# Run the server
MAILPIT_URL=http://localhost:8025 ./mailpit-mcp-server
Option 4: Go Install
go install github.com/amirhmoradi/mailpit-mcp/cmd/mailpit-mcp-server@latest
Configuration
Configure the MCP server using environment variables:
Usage with AI Tools
Claude Desktop
Add to your Claude Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"mailpit": {
"command": "/path/to/mailpit-mcp-server",
"env": {
"MAILPIT_URL": "http://localhost:8025"
}
}
}
}
Or if using Docker:
{
"mcpServers": {
"mailpit": {
"command": "docker",
"args": ["run", "-i", "--rm",
"-e", "MAILPIT_URL=http://host.docker.internal:8025",
"ghcr.io/amirhmoradi/mailpit-mcp:latest"]
}
}
}
Cursor / VS Code
For IDE integration, run the MCP server in HTTP mode:
# Start the server in HTTP mode
MAILPIT_URL=http://localhost:8025 MCP_TRANSPORT=http ./mailpit-mcp-server
Then add to your IDE's MCP configuration:
{
"mcp.servers": {
"mailpit": {
"url": "http://localhost:3000/mcp"
}
}
}
Available Tools
Available Prompts
Search Syntax
The search tool supports Mailpit's query syntax:
from:[email protected]- Sender addressto:[email protected]- Recipient addresssubject:keyword- Subject contains textmessage-id:id- Specific Message-IDtag:tagname- Has specific tagis:read/is:unread- Read statushas:attachment- Has attachmentsbefore:YYYY-MM-DD- Before dateafter:YYYY-MM-DD- After date
Multiple terms are combined with AND logic.
Development
# Build
cd mcp
go build ./...
# Test
go test ./...
# Run locally (STDIO mode for Claude Desktop)
MAILPIT_URL=http://localhost:8025 go run ./cmd/mailpit-mcp-server
# Run locally (HTTP mode for IDE integration)
MAILPIT_URL=http://localhost:8025 MCP_TRANSPORT=http go run ./cmd/mailpit-mcp-server
License
MIT License - See LICENSE for details.
Acknowledgments
This project provides MCP integration for Mailpit, the excellent email testing tool created by @axllent.