# Mailosaur MCP

[![CI](https://github.com/your-org/mailosaur-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/your-org/mailosaur-mcp/actions/workflows/ci.yml)

A full-featured Model Context Protocol server for Mailosaur email and SMS testing.

## Features

- List, search, wait for, retrieve, create, forward, reply to, and delete messages.
- Manage Mailosaur servers and generate test email addresses.
- Download EML files and attachments as base64 content.
- Generate and download email preview screenshots.
- Run spam and deliverability analysis.
- Inspect account limits and transaction usage.
- Create virtual security devices and retrieve TOTP codes.

The implementation is based on the official Mailosaur API and Node.js client surface. See [Mailosaur API docs](https://mailosaur.com/docs/api), [Mailosaur Node.js docs](https://mailosaur.com/docs/languages/nodejs), and [Mailosaur email previews docs](https://mailosaur.com/docs/email-previews).

## Setup

```bash
npm install
npm run build
```

Set your Mailosaur API key:

```bash
export MAILOSAUR_API_KEY="your_api_key"
```

## MCP configuration

```json
{
  "mcpServers": {
    "mailosaur": {
      "command": "node",
      "args": ["/absolute/path/to/mailosaur-mcp/dist/index.js"],
      "env": {
        "MAILOSAUR_API_KEY": "your_api_key"
      }
    }
  }
}
```

## Local development

```bash
npm run typecheck
npm run build
```

Run directly during development:

```bash
MAILOSAUR_API_KEY="your_api_key" npm run dev
```

## Tools

- `mailosaur_messages_get`
- `mailosaur_messages_list`
- `mailosaur_messages_search`
- `mailosaur_messages_get_by_id`
- `mailosaur_messages_create`
- `mailosaur_messages_forward`
- `mailosaur_messages_reply`
- `mailosaur_messages_delete`
- `mailosaur_messages_delete_all`
- `mailosaur_messages_generate_previews`
- `mailosaur_servers_list`
- `mailosaur_servers_create`
- `mailosaur_servers_get`
- `mailosaur_servers_get_password`
- `mailosaur_servers_update`
- `mailosaur_servers_delete`
- `mailosaur_servers_generate_email_address`
- `mailosaur_files_get_email`
- `mailosaur_files_get_attachment`
- `mailosaur_files_get_preview`
- `mailosaur_analysis_spam`
- `mailosaur_analysis_deliverability`
- `mailosaur_previews_list_email_clients`
- `mailosaur_devices_list`
- `mailosaur_devices_create`
- `mailosaur_devices_otp`
- `mailosaur_devices_delete`
- `mailosaur_usage_limits`
- `mailosaur_usage_transactions`

Destructive tools require `confirm: true`.

## Repository Skill

This repository includes a Codex skill at `skills/mailosaur-mcp-builder`. Use it when extending this MCP, auditing tool coverage against Mailosaur docs, or building another Mailosaur MCP implementation.