ActiveCampaign-MCP

# ohneben's ActiveCampaign MCP

[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-ohneben-FFDD00?style=for-the-badge&logo=buymeacoffee&logoColor=black)](https://buymeacoffee.com/ohneben)

---

#### License & checks

[![CI](https://github.com/ohneben/ActiveCampaign-MCP/actions/workflows/ci.yml/badge.svg)](https://github.com/ohneben/ActiveCampaign-MCP/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE.md)

#### MCP registries

[![MCP Registry](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fregistry.modelcontextprotocol.io%2Fv0.1%2Fservers%2Fio.github.ohneben%252Factivecampaign-mcp%2Fversions%2Flatest&query=%24.server.version&prefix=v&label=MCP%20Registry&color=blue&logo=modelcontextprotocol&logoColor=white)](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.ohneben%2Factivecampaign-mcp/versions/latest)
[![Listed on mcpservers.org](https://mcpservers.org/badge.svg)](https://mcpservers.org/servers/ohneben/activecampaign-mcp)
[![ActiveCampaign-MCP MCP server](https://glama.ai/mcp/servers/ohneben/ActiveCampaign-MCP/badges/score.svg)](https://glama.ai/mcp/servers/ohneben/ActiveCampaign-MCP)

**The most complete ActiveCampaign MCP server there is.** Run your entire
[ActiveCampaign](https://www.activecampaign.com/) account in plain language from
**Claude**, **Cursor**, or any other [MCP](https://modelcontextprotocol.io) client.

This [Model Context Protocol](https://modelcontextprotocol.io) server exposes the
**whole ActiveCampaign account API — ~325 tools** — covering the v3 REST API plus
the **SMS**, **WhatsApp** and async **Segments** APIs, generated straight from
ActiveCampaign's own OpenAPI definitions. Every tool is **safety-categorized**
(🟢 read-only / 🟡 write / 🔴 destructive) so your assistant knows what an action
does *before* it calls it. It runs over **stdio** (Claude Desktop and other local
launchers) or **Streamable HTTP** (hosted in Docker), and ships with retries,
client-side rate limiting tuned to ActiveCampaign's 5 req/s cap, and request
timeouts so it holds up against a live account.

## Why you'll want this

Some MCP servers just forward a slice of the API. This one is built to be **safe
to hand to an LLM**, **complete**, and **easy to run for real**:

| What you get | Why it matters |
| --- | --- |
| **~325 tools — the full account API** | Complete coverage of contacts, deals, accounts, lists, tags, custom fields & objects, ecommerce (deep data), campaigns, messages, automations, segments, webhooks, tasks, calendars, site/event tracking, SMS and WhatsApp — nothing hand-picked or left behind. Other servers stop at ~60. |
| **Curated safety categories** 🟢 / 🟡 / 🔴 | Not naive "GET = safe": `contact sync` is flagged as an **upsert**, a segment-match `POST` as a **read-only query**, tagging a contact as a **link**, and `POST /sms/broadcasts` as **sends messages** — so the model knows the real blast radius. |
| **Machine-readable MCP annotations** (`readOnlyHint`, `destructiveHint`) | Hosts that honor annotations (Claude included) can auto-trust reads and demand confirmation before anything destructive. |
| **Read-only mode & resource filtering** | Expose only 🟢 read-only tools (`ACTIVECAMPAIGN_READ_ONLY=true`), or narrow to just the groups you use (`ACTIVECAMPAIGN_INCLUDE_GROUPS=contacts,deals,lists`). Tailor the surface per deployment. |
| **Pagination made first-class** | `limit`, `offset`, `orders[…]` and `filters[…]` are injected onto every list endpoint as typed inputs, so the assistant can page, sort and filter without guessing ActiveCampaign's bracket syntax. |
| **Automatic retries with backoff** | Transient `429` / `5xx` responses are retried with jittered exponential backoff, honoring the server's `Retry-After` header. |
| **Built-in rate limiting** | Self-throttles under ActiveCampaign's **5 requests / second** account cap so a burst of tool calls never trips a `429`. |
| **Response-size guard** | Optionally cap huge list responses (`ACTIVECAMPAIGN_MAX_RESPONSE_CHARS`) so one call can't blow the model's context window. |
| **GraphQL passthrough** | A bonus tool for ActiveCampaign's Ecommerce GraphQL API when you want to shape exactly the fields you need in one round-trip. |
| **Two transports: stdio *and* Streamable HTTP** | Use it locally in Claude Desktop, or run one always-on server that any number of MCP clients reach over HTTP. |
| **Docker + docker-compose, health check, auto-restart** | Production-style deployment out of the box: `docker compose up` and it stays up. |
| **Optional bearer-token auth** on the HTTP endpoint | Put the server behind a shared secret the moment it's reachable beyond localhost. |
| **Your token never reaches the model** | The `Api-Token` lives in the server's environment and is injected on every request — the assistant only ever sees tool inputs and API responses. |
| **Drop-in spec updates** | ActiveCampaign ships newer OpenAPI JSON? Replace the file in `spec/` and rebuild — new endpoints become new tools automatically, no code changes. |

## How it compares

There are a few ways to reach ActiveCampaign from an AI assistant today. Here's how
this server stacks up against the alternatives:

| | **This server** | Official AC remote MCP | HighLiuk `mcp-server-activecampaign` | `mcp-activecampaign` (PyPI) | CData MCP |
|---|:---:|:---:|:---:|:---:|:---:|
| Approx. tools | **~325** | curated subset | 58 | ~65 | 3 (generic SQL) |
| Full v3 REST coverage | ✅ | ➖ | ➖ core CRM | ➖ broad CRM | ❌ |
| SMS · WhatsApp · Segments | ✅ | ❌ | ❌ | ❌ | ❌ |
| Ecommerce deep data + GraphQL | ✅ | ➖ | ❌ | ➖ | ❌ |
| Reads **and** writes | ✅ | ✅ | ✅ | ✅ | ❌ read-only |
| Self-hosted on your own infra | ✅ | ❌ vendor cloud | ✅ | ✅ | ✅ |
| Connects directly to the AC API | ✅ | ✅ | ✅ | ✅ | ❌ via JDBC driver |
| `stdio` transport | ✅ | ❌ | ✅ | ✅ | ✅ |
| Streamable-HTTP transport | ✅ | ✅ | ➖ | ➖ | ❌ |
| Docker + compose + health check | ✅ | n/a | ❌ | ❌ | ❌ |
| Curated 🟢 / 🟡 / 🔴 safety categories | ✅ | ➖ | ➖ partial | ➖ | n/a |
| `readOnlyHint` / `destructiveHint` | ✅ | ➖ | ➖ | ➖ | ➖ |
| Read-only mode + group filtering | ✅ | ❌ | ❌ | ❌ | always read-only |
| Rate limiting + auto-retry (`429`/`5xx`) | ✅ | ➖ | ❌ | ➖ | ❌ |
| Language | TypeScript | — | TypeScript | Python | Java |
| License | MIT | proprietary | MIT | MIT | MIT |

<sub>✅ = yes · ➖ = partial / not documented · ❌ = no. Compiled from each project's
public documentation; this is an unofficial project, not affiliated with
ActiveCampaign or the projects listed. Tool counts are approximate and move as APIs
evolve.</sub>

**The short version:** the official remote MCP is a great managed on-ramp but runs
in ActiveCampaign's cloud on a curated slice of the API. The community servers are
solid but top out around 60 tools of core CRM, stdio-only, without a deployment
story. This one gives you **the entire account API**, **both transports**, a
**Docker deployment**, and **safety guardrails** — self-hosted, on your token, MIT.

## What you can do

Once it's connected, ask your assistant things like:

- "Find the contact jane@example.com and show her tags, lists and recent activity."
- "Create a deal for Acme Corp worth $12,000 in the 'Sales' pipeline, stage 'Qualified'."
- "List contacts added this month who opened the last campaign but haven't been tagged 'engaged'."
- "Add the tag 'webinar-2026' to every contact on list 5."
- "Show total ecommerce revenue and the top 10 orders from last week."
- "Create a segment of customers in Germany and count how many match."
- "Draft an SMS broadcast to the 'VIP' list — but don't send it until I confirm."

Tools are generated automatically from ActiveCampaign's specs and grouped into
🟢 read-only, 🟡 write and 🔴 destructive — so a well-behaved host can treat each
group differently.

## How it works

```
Claude / Cursor / any MCP client  ──MCP──►  this server  ──HTTPS──►  ActiveCampaign API (your account)
```

The server parses the bundled OpenAPI definitions into MCP tools (resolving
`$ref`s and guarding against recursive schemas), tags each with a curated safety
category, and injects your `Api-Token` header on every outgoing request. Your
token stays in the server's environment — the model never sees or handles it.

## Requirements

- An **ActiveCampaign account with API access** — your **API URL** and **API
  token** from **Settings → Developer**. See
  [Get your API credentials](#get-your-api-credentials).
- **Docker** (Docker Desktop on macOS/Windows) for the quick start below — or
  **Node.js ≥ 18** to [run from source](#run-from-source-stdio-no-docker).

## Quick start (Docker)

**1. Add your credentials.** Copy the example config and fill it in:

```bash
cp .env.example .env
# edit .env → set ACTIVECAMPAIGN_API_URL and ACTIVECAMPAIGN_API_TOKEN
#           → set MCP_AUTH_TOKEN to a long random string if reachable beyond localhost
```

**2. Start the server:**

```bash
docker compose up -d --build
```

The bundled `docker-compose.yml` binds to `127.0.0.1:8765` only, so the server is
reachable from your machine but not the network.

**3. Confirm it's running:**

```bash
curl -s http://localhost:8765/health
# → {"status":"ok","server":"activecampaign-mcp","tools":325}
```

**4. Connect your MCP client.** The MCP endpoint is `http://localhost:8765/mcp`.

- **Claude Desktop** — add a **custom connector** (Settings → Connectors) pointing
  at the URL, or bridge it locally with
  [`mcp-remote`](https://www.npmjs.com/package/mcp-remote). Add this under
  `mcpServers` in your config, then fully quit and reopen the app:

  ```json
  {
    "mcpServers": {
      "activecampaign": {
        "command": "npx",
        "args": [
          "mcp-remote",
          "http://localhost:8765/mcp",
          "--header", "Authorization: Bearer YOUR_MCP_AUTH_TOKEN"
        ]
      }
    }
  }
  ```

  (Drop the `--header` line if you left `MCP_AUTH_TOKEN` empty.)

- **Claude Code** — one command:

  ```bash