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

Related MCP server: MCP Email Server

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

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:

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.

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.

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