MailDevMcp
English | 日本語
mcp-name: io.github.pierre3/maildev-mcp
An MCP (Model Context Protocol) server for MailDev.
Manage MailDev Docker containers and inspect received emails directly from your AI-powered editor or MCP client.
This server is intended for local development and test automation scenarios where an MCP client needs to:
- start or stop a MailDev container
- inspect inbox contents
- wait for emails after triggering application behavior
- inspect HTML bodies and attachments
- verify attachment integrity byte-for-byte
Installation
Install as a global .NET tool:
dotnet tool install -g MailDevMcp
After installation, the maildev-mcp command becomes available.
MCP Client Configuration
Add the following to your MCP client settings (e.g. Claude Desktop, VS Code, etc.):
{
"mcpServers": {
"maildev-mcp": {
"command": "maildev-mcp",
"env": {
"MAILDEV_API_PORT": "1080"
}
}
}
}
Environment Variables
| Variable | Default | Description |
|---|---|---|
MAILDEV_API_PORT | 1080 | Port number for the MailDev REST API |
Typical Workflow
- Call
StartMaildevto launch a local MailDev container - Trigger your application to send an email
- Call
WaitForEmailif delivery is asynchronous - Use
ListEmails,SearchEmails, orGetEmailto inspect the result - Use
GetEmailHtml,GetAttachmentContent, orVerifyAttachmentwhen deeper validation is needed - Clean up with
DeleteEmail,DeleteAllEmails, orStopMaildev
Available Tools
| Tool | Description |
|---|---|
StartMaildev | Start the MailDev Docker container with configurable SMTP port, API port, authentication, and TLS |
StopMaildev | Stop and remove the MailDev Docker container |
MaildevStatus | Check the running status of MailDev |
ListEmails | Retrieve the list of received emails |
GetEmail | Get the details of an email by ID, including attachment information |
GetEmailHtml | Get the HTML body of an email by ID |
SearchEmails | Search received emails by subject, sender, or recipient |
DeleteEmail | Delete a single email by ID |
DeleteAllEmails | Delete all received emails |
WaitForEmail | Wait until a new email matching given criteria arrives (useful for test automation) |
GetAttachmentContent | Get the raw Base64-encoded content of an email attachment |
VerifyAttachment | Verify that an email attachment matches the original data by byte-by-byte comparison |
Tool Behavior Notes
StartMaildev- Supports custom SMTP and API ports
- Supports optional SMTP authentication
- Treats empty or whitespace-only credentials as authentication disabled
- Supports TLS with a generated self-signed certificate
GetEmailandListEmails- Render missing or empty subjects as
(no subject) - Render missing address lists as
(none)
- Render missing or empty subjects as
WaitForEmail- Polls MailDev until a matching email arrives or the timeout is reached
- Reports transient MailDev connection failures in the returned message when they occur during polling
VerifyAttachment- Accepts a Base64-encoded original payload
- Compares the received attachment byte-by-byte
- Reports either exact match, size mismatch, or content mismatch
Requirements and Assumptions
- Docker must be installed and available on the same machine where this MCP server runs
- MailDev is accessed through its HTTP API on
localhost - The configured API port in the MCP client must match the MailDev API port exposed by Docker
Prerequisites
- .NET 10 SDK or later
- Docker (for running the MailDev container)
Building from Source
git clone https://github.com/pierre3/MailDevMcp.git
cd MailDevMcp
dotnet pack -c Release
dotnet tool install -g --add-source ./bin/Release MailDevMcp