# maildev-mcp [Health: Active]

**Category:** ☁️ Cloud Platforms  
**Repository:** https://github.com/pierre3/MailDevMcp  
**GitHub Stars:** 2  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/maildev-mcp

## Description
MailDev MCP server. Manage Docker containers and inspect emails from your AI editor or MCP client.

## Tools
Capabilities this server exposes over MCP:

- **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

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "maildev-mcp": {
    "command": "npx",
    "args": ["-y","maildev-mcp"]
  }
}
```

## Documentation & README

# MailDevMcp

English | [日本語](https://github.com/pierre3/MailDevMcp/blob/HEAD/README.ja.md)

[![CI](https://github.com/pierre3/MailDevMcp/actions/workflows/ci.yml/badge.svg)](https://github.com/pierre3/MailDevMcp/actions/workflows/ci.yml)
[![NuGet](https://img.shields.io/nuget/v/MailDevMcp.svg)](https://www.nuget.org/packages/MailDevMcp)

mcp-name: io.github.pierre3/maildev-mcp

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server for [MailDev](https://github.com/maildev/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:

```sh
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.):

```json
{
  "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

1. Call `StartMaildev` to launch a local MailDev container
2. Trigger your application to send an email
3. Call `WaitForEmail` if delivery is asynchronous
4. Use `ListEmails`, `SearchEmails`, or `GetEmail` to inspect the result
5. Use `GetEmailHtml`, `GetAttachmentContent`, or `VerifyAttachment` when deeper validation is needed
6. Clean up with `DeleteEmail`, `DeleteAllEmails`, or `StopMaildev`

## 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
- `GetEmail` and `ListEmails`
  - Render missing or empty subjects as `(no subject)`
  - Render missing address lists as `(none)`
- `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](https://dotnet.microsoft.com/) or later
- [Docker](https://www.docker.com/) (for running the MailDev container)

## Building from Source

```sh
git clone https://github.com/pierre3/MailDevMcp.git
cd MailDevMcp
dotnet pack -c Release
dotnet tool install -g --add-source ./bin/Release MailDevMcp
```
## License

[MIT](https://github.com/pierre3/MailDevMcp/blob/HEAD/LICENSE)