{"id":27311673,"url":"https://github.com/railsware/mailtrap-mcp","last_synced_at":"2025-12-30T02:07:44.907Z","repository":{"id":286103573,"uuid":"954200084","full_name":"railsware/mailtrap-mcp","owner":"railsware","description":"Official mailtrap.io MCP server","archived":false,"fork":false,"pushed_at":"2025-04-09T20:28:57.000Z","size":266,"stargazers_count":15,"open_issues_count":0,"forks_count":0,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-04-12T06:05:08.814Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://mailtrap.io","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/railsware.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-24T17:59:54.000Z","updated_at":"2025-04-09T21:31:04.000Z","dependencies_parsed_at":"2025-04-04T11:40:54.467Z","dependency_job_id":null,"html_url":"https://github.com/railsware/mailtrap-mcp","commit_stats":null,"previous_names":["railsware/mailtrap-mcp"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/railsware%2Fmailtrap-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/railsware%2Fmailtrap-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/railsware%2Fmailtrap-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/railsware%2Fmailtrap-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/railsware","download_url":"https://codeload.github.com/railsware/mailtrap-mcp/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248537146,"owners_count":21120711,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-04-12T06:03:00.135Z","updated_at":"2025-12-30T02:07:44.894Z","avatar_url":"https://github.com/railsware.png","language":"TypeScript","funding_links":[],"categories":["Official Servers","Email and Messaging","Communication","カテゴリ","🌐 Web Development","Communication \u0026 Messaging"],"sub_categories":["How to Submit","💬 \u003ca name=\"communication\"\u003e\u003c/a\u003eコミュニケーション"],"readme":"![TypeScript](https://img.shields.io/npm/types/mailtrap?logo=typescript\u0026logoColor=white\u0026label=%20)\n[![test](https://github.com/mailtrap/mailtrap-mcp/actions/workflows/main.yml/badge.svg)](https://github.com/mailtrap/mailtrap-mcp/actions/workflows/main.yml)\n[![NPM](https://shields.io/npm/v/mcp-mailtrap?logo=npm\u0026logoColor=white)](https://www.npmjs.com/package/mcp-mailtrap)\n\n# MCP Mailtrap Server\n\nAn MCP server that provides tools for sending transactional emails and managing email templates via Mailtrap\n\n## Prerequisites\n\nBefore using this MCP server, you need to:\n\n1. [Create a Mailtrap account](https://mailtrap.io/signup)\n2. [Verify your domain](https://mailtrap.io/sending/domains)\n3. Get your API token from [Mailtrap API settings](https://mailtrap.io/api-tokens)\n4. Get your Account ID from [Mailtrap account management](https://mailtrap.io/account-management)\n\n**Required Environment Variables:**\n- `MAILTRAP_API_TOKEN` - Required for all functionality\n- `DEFAULT_FROM_EMAIL` - Required for all email sending operations\n- `MAILTRAP_ACCOUNT_ID` - Required for template management operations\n- `MAILTRAP_TEST_INBOX_ID` - **Only** required for sandbox email functionality\n\n## Quick Install\n\n[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=mailtrap\u0026config=eyJlbnYiOnsiTUFJTFRSQVBfQVBJX1RPS0VOIjoieW91cl9tYWlsdHJhcF9hcGlfdG9rZW4iLCJERUZBVUxUX0ZST01fRU1BSUwiOiJ5b3VyX3NlbmRlckBleGFtcGxlLmNvbSIsIk1BSUxUUkFQX0FDQ09VTlRfSUQiOiJ5b3VyX2FjY291bnRfaWQiLCJNQUlMVFJBUF9URVNUX0lOQk9YX0lEIjoieW91cl90ZXN0X2luYm94X2lkIn0sImNvbW1hbmQiOiJucHggLXkgbWNwLW1haWx0cmFwIn0%3D)\n\n[![Install with Node in VS Code](https://img.shields.io/badge/VS_Code-Node-0098FF?style=flat-square\u0026logo=visualstudiocode\u0026logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=mailtrap\u0026config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22mcp-mailtrap%22%5D%2C%22env%22%3A%7B%22MAILTRAP_API_TOKEN%22%3A%22%24%7Binput%3AmailtrapApiToken%7D%22%2C%22DEFAULT_FROM_EMAIL%22%3A%22%24%7Binput%3AsenderEmail%7D%22%2C%22MAILTRAP_ACCOUNT_ID%22%3A%22%24%7Binput%3AmailtrapAccountId%7D%22%2C%22MAILTRAP_TEST_INBOX_ID%22%3A%22%24%7Binput%3AmailtrapTestInboxId%7D%22%7D%7D\u0026inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22mailtrapApiToken%22%2C%22description%22%3A%22Mailtrap+API+Token%22%2C%22password%22%3Atrue%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22senderEmail%22%2C%22description%22%3A%22Sender+Email+Address%22%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22mailtrapAccountId%22%2C%22description%22%3A%22Mailtrap+Account+ID%22%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22mailtrapTestInboxId%22%2C%22description%22%3A%22Mailtrap+Test+Inbox+ID+%28optional%29%22%7D%5D)\n\n\n\n### Smithery CLI\n\n[Smithery](https://github.com/smithery-ai/cli) is a registry installer and manager for MCP servers that works with all AI clients.\n\n```\nnpx @smithery/cli install mailtrap\n```\n\n\u003e Smithery automatically handles client configuration and provides an interactive setup process. It's the easiest way to get started with MCP servers locally.\n\n\n\n## Setup\n### Claude Desktop\nUse MCPB to install the Mailtrap server. You can find those files in [Releases](https://github.com/mailtrap/mailtrap-mcp/releases). \u003cbr\u003eDownload .MCPB file and open it. If you have Claude Desktop - it will open it and suggest to configure.\n\n### Claude Desktop or Cursor\n\nAdd the following configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"mailtrap\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-mailtrap\"],\n      \"env\": {\n        \"MAILTRAP_API_TOKEN\": \"your_mailtrap_api_token\",\n        \"DEFAULT_FROM_EMAIL\": \"your_sender@example.com\",\n        \"MAILTRAP_ACCOUNT_ID\": \"your_account_id\",\n        \"MAILTRAP_TEST_INBOX_ID\": \"your_test_inbox_id\"\n      }\n    }\n  }\n}\n```\n\nIf you are using `asdf` for managing Node.js you must use absolute path to executable (example for Mac)\n\n```json\n{\n  \"mcpServers\": {\n    \"mailtrap\": {\n      \"command\": \"/Users/\u003cusername\u003e/.asdf/shims/npx\",\n      \"args\": [\"-y\", \"mcp-mailtrap\"],\n      \"env\": {\n        \"PATH\": \"/Users/\u003cusername\u003e/.asdf/shims:/usr/bin:/bin\",\n        \"ASDF_DIR\": \"/opt/homebrew/opt/asdf/libexec\",\n        \"ASDF_DATA_DIR\": \"/Users/\u003cusername\u003e/.asdf\",\n        \"ASDF_NODEJS_VERSION\": \"20.6.1\",\n        \"MAILTRAP_API_TOKEN\": \"your_mailtrap_api_token\",\n        \"DEFAULT_FROM_EMAIL\": \"your_sender@example.com\",\n        \"MAILTRAP_ACCOUNT_ID\": \"your_account_id\",\n        \"MAILTRAP_TEST_INBOX_ID\": \"your_test_inbox_id\"\n      }\n    }\n  }\n}\n```\n\n#### Claude Desktop config file location\n\n**Mac**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n#### Cursor config file location\n\n**Mac**: `~/.cursor/mcp.json`\n\n**Windows**: `%USERPROFILE%\\.cursor\\mcp.json`\n\n### VS Code\n\n\n#### Manually changing config\n\nRun in Command Palette: `Preferences: Open User Settings (JSON)`\n\nThen, in the settings file, add the following configuration:\n\n```json\n{\n  \"mcp\": {\n    \"servers\": {\n      \"mailtrap\": {\n        \"command\": \"npx\",\n        \"args\": [\"-y\", \"mcp-mailtrap\"],\n        \"env\": {\n          \"MAILTRAP_API_TOKEN\": \"your_mailtrap_api_token\",\n          \"DEFAULT_FROM_EMAIL\": \"your_sender@example.com\",\n          \"MAILTRAP_ACCOUNT_ID\": \"your_account_id\",\n          \"MAILTRAP_TEST_INBOX_ID\": \"your_test_inbox_id\"\n        }\n      }\n    }\n  }\n}\n```\n\n\u003e [!TIP]\n\u003e Don't forget to restart your MCP server after changing the \"env\" section.\n\n### MCP Bundle (MCPB)\n\nFor easy installation in hosts that support MCP Bundles, you can distribute an `.mcpb` bundle file.\n\n```bash\n# Build TypeScript and pack the MCPB bundle\nnpm run mcpb:pack\n\n# Inspect bundle metadata\nnpm run mcpb:info\n\n# Sign the bundle for distribution (optional)\nnpm run mcpb:sign\n```\n\nThis creates `mailtrap-mcp.mcpb` using the repository `manifest.json` and built artifacts in `dist/`.\n\n## Usage\n\nOnce configured, you can ask agent to send emails and manage templates, for example:\n\n**Email Operations:**\n\n- \"Send an email to john.doe@example.com with the subject 'Meeting Tomorrow' and a friendly reminder about our upcoming meeting.\"\n- \"Email sarah@example.com about the project update, and CC the team at team@example.com\"\n- \"Send a sandbox email to test@example.com with subject 'Test Template' to preview how our welcome email looks\"\n\n**Sandbox Operations:**\n\n- \"Get all messages from my sandbox inbox\"\n- \"Show me the first page of sandbox messages\"\n- \"Search for messages containing 'test' in my sandbox inbox\"\n- \"Show me the details of sandbox message with ID 5159037506\"\n\n**Template Operations:**\n\n- \"List all email templates in my Mailtrap account\"\n- \"Create a new email template called 'Welcome Email' with subject 'Welcome to our platform!'\"\n- \"Update the template with ID 12345 to change the subject to 'Updated Welcome Message'\"\n- \"Delete the template with ID 67890\"\n\n## Available Tools\n\n### send-email\n\nSends a transactional email through Mailtrap.\n\n**Parameters:**\n\n- `to` (required): Email address(es) of the recipient(s) - can be a single email or array of emails\n- `subject` (required): Email subject line\n- `from` (optional): Email address of the sender, if not provided \"DEFAULT_FROM_EMAIL\" will be used\n- `text` (optional): Email body text, required if \"html\" is empty\n- `html` (optional): HTML version of the email body, required if \"text\" is empty\n- `cc` (optional): Array of CC recipient email addresses\n- `bcc` (optional): Array of BCC recipient email addresses\n- `category` (required): Email category for tracking and analytics\n\n### send-sandbox-email\n\nSends 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.\n\n**Parameters:**\n\n- `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)\n- `subject` (required): Email subject line\n- `from` (optional): Email address of the sender, if not provided \"DEFAULT_FROM_EMAIL\" will be used\n- `text` (optional): Email body text, required if \"html\" is empty\n- `html` (optional): HTML version of the email body, required if \"text\" is empty\n- `cc` (optional): Array of CC recipient email addresses\n- `bcc` (optional): Array of BCC recipient email addresses\n- `category` (optional): Email category for tracking\n\n\u003e [!NOTE]\n\u003e 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.\n\n### get-sandbox-messages\n\nRetrieves a list of messages from your Mailtrap test inbox. Useful for checking what emails have been received in your sandbox during testing.\n\n**Parameters:**\n\n- `page` (optional): Page number for pagination (minimum: 1)\n- `last_id` (optional): Pagination using last message ID. Returns messages after the specified message ID (minimum: 1)\n- `search` (optional): Search query to filter messages\n\n\u003e [!NOTE]\n\u003e 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.\n\n### show-sandbox-email-message\n\nShows detailed information and content of a specific email message from your Mailtrap test inbox, including HTML and text body content.\n\n**Parameters:**\n\n- `message_id` (required): ID of the sandbox email message to retrieve\n\n\u003e [!NOTE]\n\u003e 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.\n\n### create-template\n\nCreates a new email template in your Mailtrap account.\n\n**Parameters:**\n\n- `name` (required): Name of the template\n- `subject` (required): Email subject line\n- `html` (or `text` is required): HTML content of the template\n- `text` (or `html` is required): Plain text version of the template\n- `category` (optional): Template category (defaults to \"General\")\n\n### list-templates\n\nLists all email templates in your Mailtrap account.\n\n**Parameters:**\n\n- No parameters required\n\n### update-template\n\nUpdates an existing email template.\n\n**Parameters:**\n\n- `template_id` (required): ID of the template to update\n- `name` (optional): New name for the template\n- `subject` (optional): New email subject line\n- `html` (optional): New HTML content of the template\n- `text` (optional): New plain text version of the template\n- `category` (optional): New category for the template\n\n\u003e [!NOTE]\n\u003e At least one updatable field (name, subject, html, text, or category) must be provided when calling update-template to perform an update.\n\n### delete-template\n\nDeletes an existing email template.\n\n**Parameters:**\n\n- `template_id` (required): ID of the template to delete\n\n## Development\n\n1. Clone the repository:\n\n```bash\ngit clone https://github.com/mailtrap/mailtrap-mcp.git\ncd mailtrap-mcp\n```\n\n2. Install dependencies:\n\n```bash\nnpm install\n```\n\n### Configuration with Claude Desktop or Cursor\n\n\u003e [!TIP]\n\u003e See the location of the config file in the [Setup](#setup) section.\n\nAdd the following configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"mailtrap\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/mailtrap-mcp/dist/index.js\"],\n      \"env\": {\n        \"MAILTRAP_API_TOKEN\": \"your_mailtrap_api_token\",\n        \"DEFAULT_FROM_EMAIL\": \"your_sender@example.com\",\n        \"MAILTRAP_ACCOUNT_ID\": \"your_account_id\",\n        \"MAILTRAP_TEST_INBOX_ID\": \"your_test_inbox_id\"\n      }\n    }\n  }\n}\n```\n\nIf you are using `asdf` for managing Node.js you should use absolute path to executable:\n\n(example for Mac)\n\n```json\n{\n  \"mcpServers\": {\n    \"mailtrap\": {\n      \"command\": \"/Users/\u003cusername\u003e/.asdf/shims/node\",\n      \"args\": [\"/path/to/mailtrap-mcp/dist/index.js\"],\n      \"env\": {\n        \"PATH\": \"/Users/\u003cusername\u003e/.asdf/shims:/usr/bin:/bin\",\n        \"ASDF_DIR\": \"/opt/homebrew/opt/asdf/libexec\",\n        \"ASDF_DATA_DIR\": \"/Users/\u003cusername\u003e/.asdf\",\n        \"ASDF_NODEJS_VERSION\": \"20.6.1\",\n        \"MAILTRAP_API_TOKEN\": \"your_mailtrap_api_token\",\n        \"DEFAULT_FROM_EMAIL\": \"your_sender@example.com\",\n        \"MAILTRAP_ACCOUNT_ID\": \"your_account_id\",\n        \"MAILTRAP_TEST_INBOX_ID\": \"your_test_inbox_id\"\n      }\n    }\n  }\n}\n```\n\n### VS Code\n\n\u003e [!TIP]\n\u003e See the location of the config file in the [Setup](#setup) section.\n\n```json\n{\n  \"mcp\": {\n    \"servers\": {\n      \"mailtrap\": {\n        \"command\": \"node\",\n        \"args\": [\"/path/to/mailtrap-mcp/dist/index.js\"],\n        \"env\": {\n          \"MAILTRAP_API_TOKEN\": \"your_mailtrap_api_token\",\n          \"DEFAULT_FROM_EMAIL\": \"your_sender@example.com\",\n          \"MAILTRAP_ACCOUNT_ID\": \"your_account_id\",\n          \"MAILTRAP_TEST_INBOX_ID\": \"your_test_inbox_id\"\n        }\n      }\n    }\n  }\n}\n```\n\n## Testing\n\nYou can test the server using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):\n\n```bash\nnpm run dev\n```\n\n### Running the MCPB Server\n\n```bash\n# Run the MCPB server directly\nnode dist/mcpb-server.js\n\n# Or use the provided binary\nmailtrap-mcpb-server\n```\n\n\u003e [!TIP]\n\u003e For development with the MCP Inspector:\n\n```bash\nnpm run dev:mcpb\n```\n\n## Error Handling\n\nThis server uses structured error handling aligned with MCP conventions:\n\n- `VALIDATION_ERROR`: Input validation failures\n- `CONFIGURATION_ERROR`: Missing or invalid configuration\n- `EXECUTION_ERROR`: Runtime execution errors\n- `TIMEOUT`: Operation timeout (30 seconds default)\n\nErrors include actionable messages and are logged in structured form.\n\n## Security\n\n- Input validated via Zod schemas\n- Environment variables handled securely\n- Timeout protection on operations (30 seconds)\n- Sensitive details sanitized in error output\n\n## Logging\n\nStructured JSON logs with levels: INFO, WARN, ERROR, DEBUG.\n\nEnable debug logging by setting `DEBUG=true`.\n\n```bash\n# Example: enable debug logging\nDEBUG=true node dist/mcpb-server.js\n```\n\n\u003e 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.\n\nLog analysis example using `jq`:\n\n```bash\n# Filter error logs\nnode dist/mcpb-server.js 2\u003e\u00261 | jq 'select(.level == \"error\")'\n\n# Filter debug logs\nnode dist/mcpb-server.js 2\u003e\u00261 | jq 'select(.level == \"debug\")'\n```\n\n## Troubleshooting\n\nCommon issues:\n\n1. Missing API Token: ensure `MAILTRAP_API_TOKEN` is set\n2. Sandbox not working: verify `MAILTRAP_TEST_INBOX_ID` is configured\n3. Timeout errors: check network connectivity and Mailtrap API status\n4. Validation errors: ensure all required fields are provided\n\n## Contributing\n\nBug reports and pull requests are welcome on [GitHub](https://github.com/mailtrap/mailtrap-mcp). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](CODE_OF_CONDUCT.md).\n\n## License\n\nThe package is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n\n## Code of Conduct\n\nEveryone interacting in the Mailtrap project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frailsware%2Fmailtrap-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frailsware%2Fmailtrap-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frailsware%2Fmailtrap-mcp/lists"}