# 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](https://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](#listaddresses)
- [Listing all messages for a given address](#listmessages)
- [Listing sent outbound messages](#listsentmessages)
- [Sending email with markdown support](#sendemail)

## Running the MCP Server

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

```bash
npm install
npm run build
```

Then run the built server:

```bash
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`):

```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:

```bash
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:

```bash
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`:

```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:

```bash
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.