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@example.com - Sender address
• to:email@example.com - Recipient address
• subject:keyword - Subject contains text
• message-id:id - Specific Message-ID
• tag:tagname - Has specific tag
• is:read / is:unread - Read status
• has:attachment - Has attachments
• before:YYYY-MM-DD - Before date
• after: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.