MCP Mailtrap Server

An MCP server that provides tools for sending and testing in sandbox via Mailtrap.

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

Required Environment Variables:

• MAILTRAP_API_TOKEN - Required for all functionality
• MAILTRAP_ACCOUNT_ID - Required for templates, 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, 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 ID for sandbox tools when sandbox_id is not provided. Enables switching between sandboxes per call via the sandbox_id parameter.
• MAILTRAP_TEST_INBOX_ID - Default test inbox ID for sandbox tools when test_inbox_id is not provided. Enables switching between inboxes per call via the test_inbox_id parameter. Legacy alias for MAILTRAP_SANDBOX_ID, still honored as a fallback.
• 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

Smithery CLI

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

npx @smithery/cli install mailtrap

Smithery automatically handles client configuration and provides an interactive setup process. It's the easiest way to get started with MCP servers locally.

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_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

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

{
  "mcpServers": {
    "mailtrap": {
      "command": "/Users/<username>/.asdf/shims/npx",
      "args": ["-y", "mcp-mailtrap"],
      "env": {
        "PATH": "/Users/<username>/.asdf/shims:/usr/bin:/bin",
        "ASDF_DIR": "/opt/homebrew/opt/asdf/libexec",
        "ASDF_DATA_DIR": "/Users/<username>/.asdf",
        "ASDF_NODEJS_VERSION": "20.6.1",
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_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_TEST_INBOX_ID": "your_test_inbox_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 using the repository manifest.json and built artifacts in dist/.

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"

Sending 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?"

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"

Tracking Opt-outs:

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

Available Tools

send-email

Sends a transactional email through Mailtrap. Supports two mutually exclusive modes — inline content (subject + text/html) or template-based (template_uuid).

Parameters: