CloudMailin MCP

An MCP (Model Context Protocol) server for integrating with the CloudMailin API. This currently uses the stdio transport and needs to be installed locally.

Overview

This project implements an MCP server that allows AI models to interact with the CloudMailin API, enabling access to email data through the Model Context Protocol. It provides tools for:

• Listing all email addresses in a CloudMailin account
• Listing all messages for a given address
• Listing sent outbound messages
• Sending email with markdown support

Running the MCP Server

To run the server, you need to provide your CloudMailin API credentials as environment variables. First, build the project:

npm install
npm run build

Then run the built server:

CLOUDMAILIN_ACCOUNT_ID=your_account_id CLOUDMAILIN_API_KEY=your_api_key CLOUDMAILIN_SMTP_URL=smtp://user:pass@host:587 CLOUDMAILIN_SENDER=sender@example.com node build/index.js

You can also integrate with Cursor / Claude Desktop for production use by adding the following to your config file (e.g. .cursor/mcp.json):

{
  "mcpServers": {
    "cloudmailin": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/workspaces/cloudmailin-mcp/build/index.js"
      ],
      "env": {
        "CLOUDMAILIN_ACCOUNT_ID": "your_account_id",
        "CLOUDMAILIN_API_KEY": "your_api_key",
        "CLOUDMAILIN_SMTP_URL": "smtp://user:pass@host:587",
        "CLOUDMAILIN_SENDER": "sender@example.com"
      }
    }
  }
}

Be sure to adjust the path if necessary, this path assumes you're just running via containers.

Environment Variables

Variable	Required	Description
CLOUDMAILIN_ACCOUNT_ID	Yes (for inbound tools)	Your CloudMailin account ID
CLOUDMAILIN_API_KEY	Yes (for inbound tools)	Your CloudMailin API key
CLOUDMAILIN_SMTP_URL	Yes (for sendEmail)	SMTP URL from your outbound account settings
CLOUDMAILIN_SENDER	No	Default sender address when from is omitted

Development

For development, you can run the server directly from TypeScript using Node.js 22.7+ with the experimental transform types flag:

CLOUDMAILIN_ACCOUNT_ID=your_account_id CLOUDMAILIN_API_KEY=your_api_key node --experimental-transform-types ./src/index.ts

Or use the provided npm script:

CLOUDMAILIN_ACCOUNT_ID=your_account_id CLOUDMAILIN_API_KEY=your_api_key npm run dev

To use Cursor in development mode, add the following to your .cursor/mcp.json:

{
  "mcpServers": {
    "cloudmailin": {
      "type": "stdio",
      "command": "npm",
      "args": [
        "--prefix",
        "/workspaces/cloudmailin-mcp",
        "run",
        "dev"
      ],
      "env": {
        "CLOUDMAILIN_ACCOUNT_ID": "test_account",
        "CLOUDMAILIN_API_KEY": "test_key"
      }
    }
  }
}

You can also run the inspector to see the MCP server in action:

npx @modelcontextprotocol/inspector node --experimental-transform-types ./src/index.ts

Available Tools

The MCP server provides tools to interact with the CloudMailin API.

listAddresses

Lists all inbound email addresses in your CloudMailin account.

Example Response:

{
  "addresses": [
    {
      "id": "address_id",
      "address": "example@cloudmailin.net",
      "created_at": "2023-01-01T00:00:00Z"
    }
  ]
}

listMessages

Lists all messages for an inbound address. You can optionally provide an addressId parameter and a query parameter to filter messages for a specific address.

The query parameter follows the elasticsearch querystring syntax and exposes the following fields:

Field	Description/Values
status	The HTTP status code your HTTP server returned
status_category	successful, delayed, failed
from	The email address of the sender
to	The email address of the recipient
subject	The subject of the email
body	The body of the email
created_at	The date and time of the email

An example query to find all messages in the last 24 hours:

status_category:delayed AND created_at:[now-1d/d TO now]

Example Response:

{
  "messages": [
    {
      "id": "message_id",
      "sender": "sender@example.com",
      "recipient": "example@cloudmailin.net",
      "subject": "Test Email",
      "created_at": "2023-01-01T00:00:00Z"
    }
  ]
}

listSentMessages

Lists sent outbound messages and their delivery status. The outbound account ID is automatically parsed from CLOUDMAILIN_SMTP_URL.

Parameter	Type	Required	Description
query	string	No	Search query to filter sent messages

Requires both CLOUDMAILIN_ACCOUNT_ID/CLOUDMAILIN_API_KEY (for API access) and CLOUDMAILIN_SMTP_URL (to identify the outbound account).

sendEmail

Send an email via CloudMailin. Prefer using the markdown field for body content — it will be automatically converted to HTML and plain text.

Parameter	Type	Required	Description
to	string	Yes	Recipient email address(es)
subject	string	Yes	Email subject line
markdown	string	No	Markdown body (preferred)
plain	string	No	Plain text body
html	string	No	HTML body
from	string	No	Sender address (defaults to CLOUDMAILIN_SENDER)
cc	string	No	CC recipient(s)
tags	string[]	No	Tags for filtering in the dashboard
testMode	boolean	No	Validate without sending

Requires CLOUDMAILIN_SMTP_URL to be set. The SMTP URL can be found in your outbound account settings in the CloudMailin dashboard.