MCP Mailtrap Server

An MCP server that provides tools for sending transactional emails and managing email templates 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
DEFAULT_FROM_EMAIL - Required for all email sending operations
MAILTRAP_ACCOUNT_ID - Required for template management operations
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"

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"

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.

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

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": "[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:

Missing API Token: ensure MAILTRAP_API_TOKEN is set
Sandbox not working: verify MAILTRAP_TEST_INBOX_ID is configured
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 189 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

License

mailtrap/mailtrap-mcp

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

send-sandbox-email

create-template

list-templates

update-template

delete-template

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 3

Packages 0

Uh oh!

Contributors 5

Uh oh!

Languages

Packages