MCP Mailtrap Server

An MCP server that provides tools for sending transactional emails, managing email templates, checking sending statistics, 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
• DEFAULT_FROM_EMAIL - Required for all email sending operations
• MAILTRAP_ACCOUNT_ID - Required for template management and sending statistics
• MAILTRAP_TEST_INBOX_ID - Only required for sandbox email functionality

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": "[email protected]",
        "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": "[email protected]",
        "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": "[email protected]",
          "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 Operations:

• "Send an email to [email protected] with the subject 'Meeting Tomorrow' and a friendly reminder about our upcoming meeting."
• "Email [email protected] about the project update, and CC the team at [email protected]"
• "Send a sandbox email to [email protected] with subject 'Test Template' to preview how our welcome email looks"

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"

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

Available Tools

send-email

Sends a transactional email through Mailtrap.

Parameters:

• to (required): Email address(es) of the recipient(s) - can be a single email or array of emails
• subject (required): Email subject line
• from (optional): Email address of the sender, if not provided "DEFAULT_FROM_EMAIL" will be used
• text (optional): Email body text, required if "html" is empty
• html (optional): HTML version of the email body, required if "text" is empty
• cc (optional): Array of CC recipient email addresses
• bcc (optional): Array of BCC recipient email addresses
• category (required): Email category for tracking and analytics

send-sandbox-email

Sends an email to your Mailtrap test inbox for development and testing purposes. This is perfect for testing email templates without sending emails to real recipients.

Parameters:

• to (required): Email address(es) of the recipient(s) - can be a single email or array of emails (will be delivered to your test inbox)
• subject (required): Email subject line
• from (optional): Email address of the sender, if not provided "DEFAULT_FROM_EMAIL" will be used
• text (optional): Email body text, required if "html" is empty
• html (optional): HTML version of the email body, required if "text" is empty
• cc (optional): Array of CC recipient email addresses
• bcc (optional): Array of BCC recipient email addresses
• category (optional): Email category for tracking

[!NOTE] The MAILTRAP_TEST_INBOX_ID environment variable must be configured for sandbox emails to work. This variable is only required for sandbox functionality and is not needed for regular transactional emails or template management.

get-sandbox-messages

Retrieves a list of messages from your Mailtrap test inbox. Useful for checking what emails have been received in your sandbox during testing.

Parameters:

• page (optional): Page number for pagination (minimum: 1)
• last_id (optional): Pagination using last message ID. Returns messages after the specified message ID (minimum: 1)
• search (optional): Search query to filter messages

[!NOTE] All parameters are optional. If none are provided, the first page of messages from the inbox will be returned. Use page for traditional pagination, last_id for cursor-based pagination, or search to filter messages by content.

show-sandbox-email-message

Shows detailed information and content of a specific email message from your Mailtrap test inbox, including HTML and text body content.

Parameters:

• message_id (required): ID of the sandbox email message to retrieve

[!NOTE] Use get-sandbox-messages first to get the list of messages and their IDs, then use this tool to view the full content of a specific message.

create-template

Creates a new email template in your Mailtrap account.

Parameters:

• name (required): Name of the template
• subject (required): Email subject line
• html (or text is required): HTML content of the template
• text (or html is required): Plain text version of the template
• category (optional): Template category (defaults to "General")

list-templates

Lists all email templates in your Mailtrap account.

Parameters:

• No parameters required

update-template

Updates an existing email template.

Parameters:

• template_id (required): ID of the template to update
• name (optional): New name for the template
• subject (optional): New email subject line
• html (optional): New HTML content of the template
• text (optional): New plain text version of the template
• category (optional): New category for the template

[!NOTE] At least one updatable field (name, subject, html, text, or category) must be provided when calling update-template to perform an update.

delete-template

Deletes an existing email template.

Parameters:

• template_id (required): ID of the template to delete

get-sending-stats

Get email sending statistics (delivery, bounce, open, click, spam rates) for a date range. Optionally break down by domain, category, email service provider, or date. Check delivery rates without leaving the editor.

Parameters:

• start_date (required): Start date for the stats range (YYYY-MM-DD)
• end_date (required): End date for the stats range (YYYY-MM-DD)
• breakdown (optional): How to break down the stats: aggregated (default), by_domain, by_category, by_email_service_provider, or by_date
• sending_domain_ids (optional): Limit results to these sending domain IDs (array of integers)
• sending_streams (optional): Limit to transactional and/or bulk (array of strings)
• categories (optional): Limit to these email categories (array of strings)
• email_service_providers (optional): Limit to these providers, e.g. Google, Yahoo, Outlook (array of strings)

[!NOTE] MAILTRAP_ACCOUNT_ID must be set for this tool to work.

Development

1. Clone the repository:

git clone https://github.com/mailtrap/mailtrap-mcp.git
cd mailtrap-mcp

2. Install dependencies:

npm install

Configuration with Claude Desktop or Cursor

[!TIP] See the location of the config file in the Setup section.

Add the following configuration:

{
  "mcpServers": {
    "mailtrap": {
      "command": "node",
      "args": ["/path/to/mailtrap-mcp/dist/index.js"],
      "env": {
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "[email protected]",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

If you are using asdf for managing Node.js you should use absolute path to executable:

(example for Mac)

{
  "mcpServers": {
    "mailtrap": {
      "command": "/Users/<username>/.asdf/shims/node",
      "args": ["/path/to/mailtrap-mcp/dist/index.js"],
      "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": "[email protected]",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

VS Code

[!TIP] See the location of the config file in the Setup section.

{
  "mcp": {
    "servers": {
      "mailtrap": {
        "command": "node",
        "args": ["/path/to/mailtrap-mcp/dist/index.js"],
        "env": {
          "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
          "DEFAULT_FROM_EMAIL": "[email protected]",
          "MAILTRAP_ACCOUNT_ID": "your_account_id",
          "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
        }
      }
    }
  }
}

Testing

You can test the server using the MCP Inspector:

npm run dev

Running the MCPB Server

# Run the MCPB server directly
node dist/mcpb-server.js

# Or use the provided binary
mailtrap-mcpb-server

[!TIP] For development with the MCP Inspector:

npm run dev:mcpb

Error Handling

This server uses structured error handling aligned with MCP conventions:

• VALIDATION_ERROR: Input validation failures
• CONFIGURATION_ERROR: Missing or invalid configuration
• EXECUTION_ERROR: Runtime execution errors
• TIMEOUT: Operation timeout (30 seconds default)

Errors include actionable messages and are logged in structured form.

Security

• Input validated via Zod schemas
• Environment variables handled securely
• Timeout protection on operations (30 seconds)
• Sensitive details sanitized in error output

Logging

Structured JSON logs with levels: INFO, WARN, ERROR, DEBUG.

Enable debug logging by setting DEBUG=true.

# Example: enable debug logging
DEBUG=true node dist/mcpb-server.js

Important: The server writes logs to stderr so stdout remains reserved for JSON-RPC frames. This prevents hosts from encountering JSON parsing errors due to interleaved logs.

Log analysis example using jq:

# Filter error logs
node dist/mcpb-server.js 2>&1 | jq 'select(.level == "error")'

# Filter debug logs
node dist/mcpb-server.js 2>&1 | jq 'select(.level == "debug")'

Troubleshooting

Common issues:

1. Missing API Token: ensure MAILTRAP_API_TOKEN is set
2. Sandbox not working: verify MAILTRAP_TEST_INBOX_ID is configured
3. Timeout errors: check network connectivity and Mailtrap API status
4. Validation errors: ensure all required fields are provided

Contributing

Bug reports and pull requests are welcome on GitHub. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The package is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Mailtrap project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.