# EmailOctopus MCP Server

[![CI](https://github.com/OfirOhan/emailoctopus-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/OfirOhan/emailoctopus-mcp/actions/workflows/ci.yml)
![MCP](https://img.shields.io/badge/MCP-compatible-blue)
![License: MIT](https://img.shields.io/badge/license-MIT-green)

A [Model Context Protocol](https://modelcontextprotocol.io) server for **[EmailOctopus](https://emailoctopus.com)**. It lets Claude, Cursor, ChatGPT and other AI agents manage your lists and contacts, read campaign results, and start automations.

> **Unofficial.** This is a community project and is not affiliated with EmailOctopus. It was built from the public [API v2 docs](https://emailoctopus.com/api-documentation/v2).

## What you can ask your agent

- "How did last Tuesday's newsletter do compared to the one before? Which links got clicked?"
- "Tag everyone who clicked the pricing link in campaign X as `hot-lead`."
- "Add these 12 webinar attendees to the **Newsletter** list with their first names and tag them `webinar-oct`."
- "Who signed up this week? Summarize by source field."
- "Unsubscribe jane@acme.com from all lists."

## Tools

| Tool | What it does | Writes? |
|---|---|---|
| `list_lists` / `get_list` | Lists with counts, fields and tags | No |
| `create_list` | Create a mailing list | Yes |
| `list_contacts` | Segment by tag, status, created/updated date range; paginated | No |
| `get_contact` | Look up by **email address** or ID | No |
| `upsert_contact` | Add or update by email, with fields, tags to add/remove, and status | Yes |
| `update_contact` | Change email, fields, tags or status (for example, unsubscribe) | Yes |
| `delete_contact` | Permanently delete a contact | **Destructive** |
| `list_campaigns` / `get_campaign` | Campaign list and details | No |
| `campaign_report` | Summary stats **plus** per-link clicks in one call | No |
| `campaign_recipients` | Who opened / clicked / bounced / did **not** open, etc. | No |
| `trigger_automation` | Queue a contact into an API-triggered automation | Yes |

Notes for agents and humans:

- Contacts can be referenced by **email address**. The server converts emails to the MD5 form EmailOctopus expects.
- Tags are sent as simple `add_tags` / `remove_tags` arrays. The server builds EmailOctopus' `{tag: true/false}` patch format for you.
- Destructive tools carry MCP `destructiveHint` annotations, so clients can ask before running them.

## Setup

1. Create an API key at **EmailOctopus → Settings → API keys**.
2. Build it:

```bash
git clone https://github.com/OfirOhan/emailoctopus-mcp.git
cd emailoctopus-mcp && npm install && npm run build
```

### Claude Desktop

```json
{
  "mcpServers": {
    "emailoctopus": {
      "command": "node",
      "args": ["/absolute/path/to/emailoctopus-mcp/dist/index.js"],
      "env": { "EMAILOCTOPUS_API_KEY": "your_api_key" }
    }
  }
}
```

### Claude Code / Cursor / other MCP clients

```bash
claude mcp add emailoctopus -e EMAILOCTOPUS_API_KEY=your_api_key -- node /path/to/emailoctopus-mcp/dist/index.js
```

## Development

```bash
npm install
npm test   # builds, runs unit tests and an end-to-end MCP stdio test against a fake EmailOctopus API
```

The tests run on Node 20, 22 and 24 in CI.

## Author

Built by [Ofir Ohana](https://github.com/OfirOhan), an AI agents engineer. Issues and PRs are welcome.

## License

MIT