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:

Create a Mailtrap account
Verify your domain
Get your API token from Mailtrap API settings
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, and sending domains. Optional only for send-email and send-sandbox-email.

Optional (can be passed as tool parameters instead):

DEFAULT_FROM_EMAIL - Default sender email when from is not provided to send-email or send-sandbox-email. Enables switching sender per call via the from 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.

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 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"
"Delete sending domain 3938"
"Get sending domain 3938 with DNS setup instructions"

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

list-email-logs

Lists sent email logs (delivery history) with optional pagination and filters. Use to debug delivery issues from the IDE.

Parameters:

search_after (optional): Pagination cursor from the previous response's next_page_cursor
sent_after (optional): ISO 8601 date/time; only logs sent after this time
sent_before (optional): ISO 8601 date/time; only logs sent before this time
from_email (optional): Filter by sender email; use with from_operator (default: ci_equal)
to_email (optional): Filter by recipient email; use with to_operator (default: ci_equal)
status (optional): Filter by delivery status: delivered, not_delivered, enqueued, opted_out; use with status_operator (default: equal)
subject (optional): Filter by email subject; use with subject_operator (default: ci_contain). Use subject_operator: empty/not_empty to filter by presence of subject.
sending_domain_id (optional): Filter by sending domain ID (number); use with sending_domain_id_operator (default: equal)
sending_stream (optional): Filter by stream: transactional or bulk; use with sending_stream_operator (default: equal)
events (optional): Filter by event type(s): delivery, open, click, bounce, spam, unsubscribe, soft_bounce, reject, suspension; use with events_operator (include_event / not_include_event)
clicks_count / opens_count (optional): Filter by click/open count; use with *_operator: equal, greater_than, less_than
client_ip / sending_ip (optional): Filter by IP; use with *_operator: equal, not_equal, contain, not_contain
email_service_provider_response (optional): Filter by provider response text; use with *_operator (ci_contain, etc.)
email_service_provider (optional): Filter by provider (exact); use with *_operator: equal, not_equal
recipient_mx (optional): Filter by recipient MX; use with recipient_mx_operator (ci_contain, etc.)
category (optional): Filter by email category; use with category_operator: equal, not_equal

All parameters are optional.

get-email-log-message

Gets a single email log message by ID (UUID): a readable summary (from, to, subject, sent time, status, category, stream, engagement, delivery context), then detailed event history. Optionally, with include_content: true, you can also load and show the message body (HTML and plain text) when Mailtrap exposes a raw message URL.

Parameters:

message_id (required): UUID of the email log message (from send response or list-email-logs). Use list-email-logs to find message IDs.
include_content (optional): When true, fetches the raw EML (if raw_message_url is available) and appends parsed HTML and plain-text body sections, similar to show-sandbox-email-message.

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)

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

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

For sandbox tools, provide test_inbox_id in the tool call or set the MAILTRAP_TEST_INBOX_ID environment variable. You can switch between inboxes per call by passing test_inbox_id.

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.

list-sending-domains

List sending domains and their DNS verification status.

Parameters:

No parameters required

get-sending-domain

Get a sending domain by ID and its verification status (including DNS records). Optionally include DNS setup instructions by setting include_setup_instructions to true.

Parameters:

sending_domain_id (required): Sending domain ID
include_setup_instructions (optional): If true, append DNS setup instructions to the response. Default: false

create-sending-domain

Create a new sending domain. After creation, add DNS records to verify the domain (use get-sending-domain with include_setup_instructions: true to see the records).

Parameters:

domain_name (required): Domain name (e.g. example.com)

delete-sending-domain

Delete a sending domain.

Parameters:

sending_domain_id (required): Sending domain ID to delete

Development

Clone the repository:

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

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": "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 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": "your_sender@example.com",
        "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": "your_sender@example.com",
          "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:

Missing API Token: ensure MAILTRAP_API_TOKEN is set
Sandbox not working: provide test_inbox_id in the tool call or set MAILTRAP_TEST_INBOX_ID env
Timeout errors: check network connectivity and Mailtrap API status
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.

Name		Name	Last commit message	Last commit date
Latest commit History 261 Commits
.github		.github
jest		jest
src		src
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.tool-versions		.tool-versions
AGENT.md		AGENT.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
LICENSE.txt		LICENSE.txt
README.md		README.md
icon.png		icon.png
jest.config.js		jest.config.js
manifest.json		manifest.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

MCP Mailtrap Server

Prerequisites

Quick Install

Smithery CLI

Setup

Claude Desktop

Claude Desktop or Cursor

Claude Desktop config file location

Cursor config file location

VS Code

Manually changing config

MCP Bundle (MCPB)

Usage

Available Tools

send-email

list-email-logs

get-email-log-message

get-sending-stats

create-template

list-templates

update-template

delete-template

send-sandbox-email

get-sandbox-messages

show-sandbox-email-message

list-sending-domains

get-sending-domain

create-sending-domain

delete-sending-domain

Development

Configuration with Claude Desktop or Cursor

VS Code

Testing

Running the MCPB Server

Error Handling

Security

Logging

Troubleshooting

Contributing

License

Code of Conduct

About

Resources

License

Code of conduct

Uh oh!

Stars

Watchers

Forks

Releases 5

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages