Mailtrap

Official Mailtrap MCP Server

The official MCP server for Mailtrap — the email delivery platform. It connects your Mailtrap account to Claude, Cursor, VS Code, and other MCP-compatible AI assistants.

Send transactional and bulk email, test messages safely in Email Sandbox, manage templates, contacts, sending domains, and webhooks, inspect email logs and delivery statistics, troubleshoot deliverability, and manage account resources — all using natural-language prompts.

Capabilities

• Email API and SMTP — Send transactional and bulk email, including batch and template-based messages.
• Email testing — Test messages in Email Sandbox and inspect content, headers, attachments, spam scores, and HTML client compatibility.
• Delivery monitoring — Search email logs, inspect event history, and analyze delivery, bounce, open, click, and spam rates.
• Email infrastructure — Manage sending domains, DNS verification, webhooks, and suppressions.
• Contacts — Manage contacts, lists, custom fields, and events, with imports and exports.
• Account management — Review billing usage and manage access, permissions, API tokens, and sub-accounts.

Supported MCP Clients

Works with Claude Desktop, Claude Code, Cursor, VS Code, and any other MCP-compatible client. Setup instructions for each are below.

Prerequisites

Before using this MCP server, you need to:

1. Create a Mailtrap account
2. Verify your domain
3. Get your API token from Mailtrap API settings
4. Get your Account ID from Mailtrap account management
5. Install Node.js 22 or later, unless you run the Docker image

Required Environment Variables:

• MAILTRAP_API_TOKEN - Required for all functionality
• MAILTRAP_ACCOUNT_ID - Required for templates, get-sending-stats, email logs, sandbox list/show, sending domains, and suppressions. Optional only for the send tools (send-email, send-sandbox-email, and the batch-send-\* tools), the email campaign tools, get-marketing-stats, the company info tools, and the tracking opt-out tools.

Optional (can be passed as tool parameters instead):

• DEFAULT_FROM_EMAIL - Default sender email when from is not provided to send-email, send-sandbox-email, or the batch-send-\* tools (where it fills base.from). Enables switching sender per call via the from parameter.
• MAILTRAP_SANDBOX_ID - Default sandbox (test inbox) ID when a tool's sandbox_id is not provided (legacy test_inbox_id on send/list/show sandbox message tools still accepted). Enables switching inboxes per call via parameters.
• MAILTRAP_TEST_INBOX_ID - Legacy alias for MAILTRAP_SANDBOX_ID; still read as a fallback for existing configs.
• MAILTRAP_ORGANIZATION_ID - Required for organization tools (list-sub-accounts, create-sub-account).
• MAILTRAP_ORGANIZATION_API_TOKEN - Organization-scoped API token. Required for organization tools (separate from MAILTRAP_API_TOKEN).

Quick Install

Docker

Run the server over stdio with the Docker MCP Catalog image:

docker run --rm -i \

-e MAILTRAP_API_TOKEN="${MAILTRAP_API_TOKEN}" \ -e MAILTRAP_ACCOUNT_ID="${MAILTRAP_ACCOUNT_ID}" \ -e DEFAULT_FROM_EMAIL="${DEFAULT_FROM_EMAIL}" \ -e MAILTRAP_SANDBOX_ID="${MAILTRAP_SANDBOX_ID}" \ -e MAILTRAP_ORGANIZATION_ID="${MAILTRAP_ORGANIZATION_ID}" \ -e MAILTRAP_ORGANIZATION_API_TOKEN="${MAILTRAP_ORGANIZATION_API_TOKEN}" \ mcp/mailtrap

See Prerequisites for required and optional environment variables.

To build from this repository: docker build -t mcp/mailtrap .

Smithery CLI

Smithery is a registry and installer for MCP servers that works with AI clients.

Install the published server (mailtrap/mailtrap-mcp) into a local client (replace the client name as needed):

npx -y smithery mcp add mailtrap/mailtrap-mcp --client claude

See the Smithery CLI docs for other clients (cursor, windsurf, etc.) and for publishing updates.

Setup

Claude Desktop

Use MCPB to install the Mailtrap server. You can find those files in Releases. Download .MCPB file and open it. If you have Claude Desktop - it will open it and suggest to configure.

Claude Desktop or Cursor

Add the following configuration:

{

"mcpServers": { "mailtrap": { "command": "npx", "args": ["-y", "mcp-mailtrap"], "env": { "MAILTRAP_API_TOKEN": "your_mailtrap_api_token", "DEFAULT_FROM_EMAIL": "your_sender@example.com", "MAILTRAP_ACCOUNT_ID": "your_account_id", "MAILTRAP_SANDBOX_ID": "your_sandbox_id" } } } }

If you are using asdf for managing Node.js you must use absolute path to executable (example for Mac)

{

"mcpServers": { "mailtrap": { "command": "/Users/ /.asdf/shims/npx", "args": ["-y", "mcp-mailtrap"], "env": { "PATH": "/Users/ /.asdf/shims:/usr/bin:/bin", "ASDF_DIR": "/opt/homebrew/opt/asdf/libexec", "ASDF_DATA_DIR": "/Users/ /.asdf", "ASDF_NODEJS_VERSION": "22.14.0", "MAILTRAP_API_TOKEN": "your_mailtrap_api_token", "DEFAULT_FROM_EMAIL": "your_sender@example.com", "MAILTRAP_ACCOUNT_ID": "your_account_id", "MAILTRAP_SANDBOX_ID": "your_sandbox_id" } } } }

Claude Desktop config file location

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Cursor config file location

Mac: ~/.cursor/mcp.json

Windows: %USERPROFILE%\.cursor\mcp.json

VS Code

Manually changing config

Run in Command Palette: Preferences: Open User Settings (JSON)

Then, in the settings file, add the following configuration:

{

"mcp": { "servers": { "mailtrap": { "command": "npx", "args": ["-y", "mcp-mailtrap"], "env": { "MAILTRAP_API_TOKEN": "your_mailtrap_api_token", "DEFAULT_FROM_EMAIL": "your_sender@example.com", "MAILTRAP_ACCOUNT_ID": "your_account_id", "MAILTRAP_SANDBOX_ID": "your_sandbox_id" } } } } }

[!TIP]

Don't forget to restart your MCP server after changing the "env" section.

MCP Bundle (MCPB)

For easy installation in hosts that support MCP Bundles, you can distribute an .mcpb bundle file.

# Build TypeScript and pack the MCPB bundle

npm run mcpb:pack

Inspect bundle metadata

npm run mcpb:info

Sign the bundle for distribution (optional)

npm run mcpb:sign

This creates mailtrap-mcp.mcpb. The script copies dist/, manifest.json, icon.png and the license into mcpb-build/, installs production dependencies there, and packs only that directory. Do not run mcpb pack . from the repository root.

Usage

Once configured, you can ask agent to send emails and manage templates, for example:

Email Sending Operations:

• "Send an email to john.doe@example.com with the subject 'Meeting Tomorrow' and a friendly reminder about our upcoming meeting."
• "Email sarah@example.com about the project update, and CC the team at team@example.com"
• "Send the welcome template (uuid b81aabcd-1a1e-41cf-91b6-eca0254b3d96) to new@example.com with variables { name: 'Alex' }"
• "Send a sandbox email to test@example.com with subject 'Test Template' to preview how our welcome email looks"

Email Logs (debug delivery):

• "List my recent sent email logs"
• "Show email logs for emails sent to user@example.com"
• "Get the email log message for ID abc-123-uuid to check delivery status"

Statistics:

• "Get sending stats for January 2025"
• "Show delivery rates broken down by domain for last month"
• "What are my email stats by category from 2025-01-01 to 2025-01-31?"
• "How did my email marketing perform last month? Compare campaigns with automations"

Sandbox Operations:

• "Get all messages from my sandbox inbox"
• "Show me the first page of sandbox messages"
• "Search for messages containing 'test' in my sandbox inbox"
• "Show me the details of sandbox message with ID 5159037506"

Template Operations:

• "List all email templates in my Mailtrap account"
• "Create a new email template called 'Welcome Email' with subject 'Welcome to our platform!'"
• "Update the template with ID 12345 to change the subject to 'Updated Welcome Message'"
• "Delete the template with ID 67890"

Sending Domains:

• "List my sending domains"
• "Get sending domain with ID 3938"
• "Create a sending domain for example.com"
• "Turn on click tracking for sending domain 3938"
• "Delete sending domain 3938"
• "Get sending domain 3938 with DNS setup instructions"
• "Show the company info for sending domain 3938"
• "Set the company info for domain 3938 to Acme Inc, 123 Main St, San Francisco, US, 94105, https://acme.com"
• "Change the company info city for domain 3938 to New York"

Suppressions:

• "List suppressions for bounced@example.com"
• "Suppress bounced@example.com on the transactional stream of domain 3938"
• "Show me all suppressed email addresses"
• "Why is user@example.com not receiving my emails?"
• "Remove user@example.com from the suppression list"

Tracking Opt-outs:

• "Stop tracking opens and clicks for privacy@example.com on domain 3938"
• "List everyone who opted out of tracking"

Contacts and Lists:

• "Add john.doe@example.com to my newsletter contact list"
• "Show me all my contact lists"
• "Create a contact field called 'signup_source' for tracking where contacts came from"
• "Update the contact john.doe@example.com to set their plan to 'pro'"
• "Import contacts from this CSV into my onboarding list"
• "Export all contacts from my newsletter list"
• "Record a 'trial_started' e