CloudMailin MCP

CloudMailin MCP

[!WARNING] This local MCP server is deprecated. CloudMailin now provides a hosted remote MCP server — no installation or API keys needed, just connect to https://mcp.cloudmailin.com/mcp and sign in. See www.cloudmailin.com/mcp for details.

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: ``json { "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: ``json { "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.