邮件陷阱MCP

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, 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.
• 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.

Quick Install

Setup

Build TypeScript and pack the MCPB bundle

npm run mcpb:pack

send-sending-domain-setup-instructions

Email DNS setup instructions for a sending domain to a given address. Useful for forwarding DNS records to a DevOps teammate.

Parameters:

• sending_domain_id (required): Sending domain ID
• email (required): Email address to send DNS setup instructions to

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

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`:

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/.

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

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.

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

Troubleshooting

Common issues:

1. Missing API Token: ensure MAILTRAP_API_TOKEN is set
2. Sandbox not working: provide test_inbox_id in the tool call or set MAILTRAP_TEST_INBOX_ID env
3. Timeout errors: check network connectivity and Mailtrap API status
4. Validation errors: ensure all required fields are provided