# mailpit_mcp

Model Context Protocol (MCP) server and HTTP client for [Mailpit](https://mailpit.axllent.org/) — 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](https://mailpit.axllent.org/docs/install/docker/) or binary)

## Install

```bash
git clone https://github.com/exabyteso/mailpit_mcp.git
cd mailpit_mcp
npm install
```

## Environment

Copy `.env.example` to `.env` locally (`.env` is gitignored). All configuration is optional:

| Variable | Default | Description |
|----------|---------|-------------|
| `MAILPIT_URL` | `http://127.0.0.1:8025` | Mailpit HTTP API base URL |
| `MAILPIT_AUTH_USER` | — | Basic auth username (if enabled on Mailpit) |
| `MAILPIT_AUTH_PASS` | — | Basic auth password |
| `MAILPIT_TIMEOUT_MS` | `30000` | HTTP request timeout |

## Run the MCP server

```bash
npm start
```

## Cursor / MCP client registration

Add to your workspace `.cursor/mcp.json`:

```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 |
|------|-------------|
| `mailpit_health` | `GET /api/v1/info` |
| `mailpit_list_messages` | Recent messages |
| `mailpit_search` | Mailpit search query |
| `mailpit_get_message` | Full message by ID |
| `mailpit_get_latest_for_recipient` | Latest mail to an address |
| `mailpit_wait_for_message` | Poll until a message matches |
| `mailpit_extract_otp` | Parse verification code from body |
| `mailpit_delete_all` | Clear mailbox (test reset) |

## Programmatic client

```javascript
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

```bash
npm test
```

Unit tests use fixtures only — no live Mailpit required.

## Security

See [SECURITY.md](SECURITY.md). This repo ships **no secrets**. Configure auth via environment variables on your machine only.

## License

MIT — see [LICENSE](LICENSE).