Mailtrap Messaging Utility

Introduction

This MCP component enables the relaying of structured digital messages using the Mailtrap infrastructure. Email operates on a store-and-forward model across networks, allowing users to send or retrieve messages without requiring simultaneous online presence. This tool specifically interfaces with Mailtrap's mechanisms for transactional delivery and management of message formats.

Prerequisites

To initialize this message relay capability, several external preparations are required:

1. Secure a credential set by registering on the Mailtrap platform.
2. Validate your designated outgoing domain within the service settings.
3. Obtain the necessary API access key from the Mailtrap administrative area.
4. Retrieve your unique Account Identifier from the platform's management section.

Mandatory Environment Settings: - MAILTRAP_API_TOKEN - Essential for invoking any service function. - DEFAULT_FROM_EMAIL - Required to designate the source address for all outgoing transmissions. - MAILTRAP_ACCOUNT_ID - Necessary when performing operations related to message template revisions. - MAILTRAP_TEST_INBOX_ID - Only needed when directing messages to the designated sandbox environment for testing.

Quick Install

Setup

Configuration for Desktop Environments (Claude or Cursor)

In the relevant configuration file, append the following JSON structure to define the server integration:

{
  "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 system path management uses asdf for Node.js versions, employing the explicit executable location is necessary (example path for macOS):

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

Configuration File Locations

Claude Desktop:

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Cursor Application:

Mac: ~/.cursor/mcp.json

Windows: %USERPROFILE%\.cursor\mcp.json

Configuration via VS Code Settings

Access the JSON settings file using the Command Palette option: Preferences: Open User Settings (JSON).

Then, incorporate this configuration structure into your settings file:

{
  "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] Remember to reactivate the MCP server process following any modification to the "env" settings.

Usage

After successful setup, instruct the agent to handle message dispatch or template maintenance tasks. Examples include:

Message Dispatch Functions:

• "Transmit a notification to john.doe@example.com regarding our scheduled appointment tomorrow, using the subject 'Meeting Reminder'."
• "Forward project status details to sarah@example.com, including team@example.com in the carbon copy recipients."
• "Dispatch a development message to test@example.com with the title 'Test Template' to check the visual rendering of our introductory communication."

Template Management Functions:

• "Retrieve a complete inventory of all existing message templates within my Mailtrap repository."
• "Establish a new message layout titled 'User Onboarding' with the designation 'Welcome to our platform!' for the subject line."
• "Modify the existing layout identified by ID 12345, setting the subject field to 'Updated Welcome Message'."
• "Permanently remove the message layout associated with identifier 67890."

Available Tools

send-email

Dispatches an application message via the Mailtrap gateway.

Parameters:

• to (required): One or multiple recipient electronic addresses for delivery.
• subject (required): The designated title line for the communication.
• from (optional): Sender address; defaults to the value of "DEFAULT_FROM_EMAIL" if omitted.
• text (optional): The plain text content; mandatory if the html parameter is left blank.
• html (optional): The styled HTML content; mandatory if the text parameter is absent.
• cc (optional): A collection of email addresses designated for carbon copying.
• bcc (optional): A collection of email addresses designated for blind carbon copying.
• category (required): The classification tag used for analytical tracking of the message.

send-sandbox-email

Sends a message copy to your Mailtrap testing environment for verification purposes. This method is ideal for previewing layouts without actual external delivery.

Parameters:

• to (required): Recipient address(es) (will route to your designated test inbox).
• subject (required): The subject line assigned to the message.
• from (optional): Sender address; defaults to "DEFAULT_FROM_EMAIL" if not specified.
• text (optional): Plain body content; required if html is not supplied.
• html (optional): HTML body content; required if text is not supplied.
• cc (optional): Array containing addresses for carbon copy recipients.
• bcc (optional): Array containing addresses for blind carbon copy recipients.
• category (optional): The tracking classification assigned to this test transmission.

[!NOTE] Configuration of the MAILTRAP_TEST_INBOX_ID environment variable is an absolute prerequisite for successful sandbox messaging. This specific variable is exclusively required for sandbox operations, not for standard transmissions or template manipulation.

create-template

Generates a new message layout within your linked Mailtrap account.

Parameters:

• name (required): The unique nomenclature assigned to the template.
• subject (required): The subject string associated with this layout.
• html (or text is required): The structured HTML markup content for the body.
• text (or html is required): The unformatted plain text version for the body.
• category (optional): The grouping label for the template (defaults to "General").

list-templates

Retrieves a catalog of all established message layouts present in your Mailtrap instance.

Parameters:

• This function requires no input arguments.

update-template

Modifies the attributes of an existing message layout.

Parameters:

• template_id (required): The specific identifier of the layout targeted for modification.
• name (optional): A new designated name for the layout.
• subject (optional): The revised subject string.
• html (optional): New content in HTML format.
• text (optional): New content in plain text format.
• category (optional): The newly assigned grouping label for the layout.

[!NOTE] To successfully execute an update operation, at least one parameter capable of modification (name, subject, html, text, or category) must be supplied with a value.

delete-template

Removes a specified message layout from active status.

Parameters:

• template_id (required): The unique identifier pointing to the layout slated for deletion.

Development

To prepare the source code for local execution or modification, follow these initial steps:

1. Obtain a copy of the repository via cloning:

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

1. Install all required software packages:

npm install

Configuration for Local Execution (Claude Desktop/Cursor)

[!TIP] Refer to the Setup section above for the specific location of your configuration file.

Integrate the subsequent JSON structure into your development environment settings:

{
  "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 Node.js version control employs asdf, the path to the executable must be absolute (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"
      }
    }
  }
}

Configuration via VS Code

[!TIP] Consult the Setup section for the precise location of the configuration file.

Apply this JSON modification to your VS Code settings:

{
  "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 execute tests against this server installation using the official MCP Inspector utility:

npm run dev

Related Topics

• Store-and-forward messaging architecture
• Digital message addressing conventions (@ symbol)
• MIME standards for multimedia content in electronic communication
• Transactional versus marketing email segregation

Extra Details

Historically, internet messaging began as strictly text-based ASCII; MIME extensions permitted the integration of richer content like images. While internationalized addresses using UTF-8 are standardized, their full adoption across all platforms remains incomplete. This tool focuses on secure, programmatic delivery, bypassing typical webmail interfaces for automated application needs.

Conclusion

This server component provides essential functionality for managing outbound communications via Mailtrap, covering both live transactional dispatch and crucial pre-send template verification. Reliable digital messaging remains central to modern operational processes across professional domains.

Contributing

We welcome community input via bug reports and proposed code modifications submitted through GitHub. This project aims to foster a cooperative environment, requiring all contributors to adhere to the stated code of conduct.

License

The software package is made available freely under the conditions established by the MIT License.

Code of Conduct

All individuals participating in the Mailtrap project's repositories, issue logs, or communication channels must conform to the established code of conduct.