内容
# ohneben's ActiveCampaign MCP
[](https://github.com/ohneben/ActiveCampaign-MCP/actions/workflows/ci.yml)
[](https://github.com/ohneben/ActiveCampaign-MCP/actions/workflows/docker-publish.yml)
[](./LICENSE.md)
**最完整的 ActiveCampaign MCP 服务器。** 在纯语言环境中运行您的整个 [ActiveCampaign](https://www.activecampaign.com/) 账户，从 **Claude**、**Cursor** 或任何其他 [MCP](https://modelcontextprotocol.io) 客户端。
本 [Model Context Protocol](https://modelcontextprotocol.io) 服务器公开了整个 **ActiveCampaign 账户 API — 约 325 个工具**，涵盖 v3 REST API 以及 **SMS**、**WhatsApp** 和异步 **Segments** API，直接从 ActiveCampaign 自己的 OpenAPI 定义中生成。每个工具都经过 **安全分类**（🟢 只读 / 🟡 写入 / 🔴 破坏性），以便您的助手在调用之前知道操作的作用。
## 为什么您需要这个
一些 MCP 服务器只转发 API 的一部分。而这个服务器旨在 **安全地交给 LLM**、**完整** 和 **易于实际运行**：
| 您获得的功能 | 原因 |
| --- | --- |
| **约 325 个工具 — 完整的账户 API** | 完整覆盖联系人、交易、账户、列表、标签、自定义字段和对象、电子商务（深入数据）、活动、消息、自动化、细分、网络钩子、任务、日历、站点/事件跟踪、SMS 和 WhatsApp — 没有精选或遗漏。其他服务器仅限于约 60 个。 |
| **精选的安全类别** 🟢 / 🟡 / 🔴 | 不是天真的“GET = 安全”：`contact sync` 被标记为 **upsert**，`segment-match POST` 被标记为 **只读查询**，`tagging a contact` 被标记为 **链接**，而 `POST /sms/broadcasts` 被标记为 **发送消息** — 以便模型知道实际的影响范围。 |
| **机器可读的 MCP 注释** (`readOnlyHint`、`destructiveHint`) | 遵循注释的主机（包括 Claude）可以自动信任读取并在破坏性操作前要求确认。 |
| **只读模式和资源过滤** | 仅公开 🟢 只读工具 (`ACTIVECAMPAIGN_READ_ONLY=true`)，或缩小到您使用的组 (`ACTIVECAMPAIGN_INCLUDE_GROUPS=contacts,deals,lists`)。根据部署情况定制接口。 |
| **分页成为一流功能** | `limit`、`offset`、`orders[…]` 和 `filters[…]` 被注入每个列表端点作为类型化输入，以便助手可以分页、排序和过滤，而无需猜测 ActiveCampaign 的括号语法。 |
| **自动重试和退避** | 暂时的 `429` / `5xx` 响应会重试并带有抖动的指数退避，同时遵守服务器的 `Retry-After` 头部。 |
| **内置速率限制** | 在 ActiveCampaign 的 **5 请求/秒** 账户上限下自我限制，以防止突发请求触发 `429`。 |
| **响应大小保护** | 可选地限制大型列表响应 (`ACTIVECAMPAIGN_MAX_RESPONSE_CHARS`)，以防止一次调用超出模型的上下文窗口。 |
| **GraphQL 直通** | 当您需要在一趟中确定要查询的字段时，为 ActiveCampaign 的电子商务 GraphQL API 提供了奖励工具。 |
| **两种传输方式：stdio 和 Streamable HTTP** | 在 Claude Desktop 上本地使用，或运行一个始终在线的服务器，任何数量的 MCP 客户端都可以通过 HTTP 访问。 |
| **Docker + docker-compose，健康检查，自动重启** | 开箱即用的生产环境部署：`docker compose up`，它会保持运行。 |
| **可选的 bearer-token 认证** 在 HTTP 端点上 | 在其可访问范围超出 localhost 之后，将服务器置于共享密钥的保护之下。 |
| **您的令牌永远不会到达模型** | `Api-Token` 存在于服务器的环境中，并在每个请求中注入 — 助手只会看到工具输入和 API 响应。 |
| **直接规范更新** | ActiveCampaign 提供了新的 OpenAPI JSON？替换 `spec/` 中的文件并重建 — 新的端点将自动成为新的工具，无需代码更改。 |
## 它是如何比较的
今天有几种方法可以从 AI 助手访问 ActiveCampaign。以下是此服务器与其他服务器的比较：
| | **此服务器** | 官方 AC 远程 MCP | HighLiuk `mcp-server-activecampaign` | `mcp-activecampaign` (PyPI) | CData MCP |
|---|:---:|:---:|:---:|:---:|:---:|
| 近似工具 | **约 325** | 精选的子集 | 58 | 约 65 | 3（通用 SQL） |
| 完整的 v3 REST 覆盖 | ✅ | ➖ | ➖ 核心 CRM | ➖ 广泛的 CRM | ❌ |
| SMS · WhatsApp · 分段 | ✅ | ❌ | ❌ | ❌ | ❌ |
| 电子商务深入数据 + GraphQL | ✅ | ➖ | ❌ | ➖ | ❌ |
| 读取 **和** 写入 | ✅ | ✅ | ✅ | ✅ | ❌ 只读 |
| 自托管在您自己的基础设施上 | ✅ | ❌ 供应商云 | ✅ | ✅ | ✅ |
| 直接连接到 AC API | ✅ | ✅ | ✅ | ✅ | ❌ 通过 JDBC 驱动程序 |
| `stdio` 传输 | ✅ | ❌ | ✅ | ✅ | ✅ |
| Streamable-HTTP 传输 | ✅ | ✅ | ➖ | ➖ | ❌ |
| Docker + 组合 + 健康检查 | ✅ | n/a | ❌ | ❌ | ❌ |
| 精选的 🟢 / 🟡 / 🔴 安全类别 | ✅ | ➖ | ➖ 部分 | ➖ | n/a |
| `readOnlyHint` / `destructiveHint` | ✅ | ➖ | ➖ | ➖ | ➖ |
| 只读模式 + 组过滤 | ✅ | ❌ | ❌ | ❌ | 始终只读 |
| 速率限制 + 自动重试 (`429`/`5xx`) | ✅ | ➖ | ❌ | ➖ | ❌ |
| 语言 | TypeScript | — | TypeScript | Python | Java |
| 许可证 | MIT | 专有 | MIT | MIT | MIT |
<sub>✅ = 是 · ➖ = 部分/未记录 · ❌ = 否。编译自每个项目的公共文档；这是一个非官方项目，与 ActiveCampaign 或列出的项目无关。工具数量是近似的，随着 API 的演变而变化。</sub>
**简短版本：** 官方远程 MCP 是一个很好的托管入口，但它在 ActiveCampaign 的云上运行，涵盖了 API 的精选部分。社区服务器很可靠，但最多只有 60 个核心 CRM 工具，仅限 stdio，没有部署故事。而此服务器提供 **整个账户 API**、**两种传输方式**、**Docker 部署** 和 **安全防护** — 自托管，使用您的令牌，MIT 许可证。
## 您可以用它做什么
连接后，询问您的助手类似的问题：
- “查找联系人 jane@example.com 并显示她的标签、列表和最近的活动。”
- “为 Acme Corp 创建一个价值 $12,000 的交易，位于 ‘销售’ 管道，阶段 ‘合格’。”
- “列出本月添加的联系人，他们打开了上一次活动，但没有被标记为 ‘参与’。”
- “将 ‘webinar-2026’ 标签添加到列表 5 中的每个联系人。”
- “显示总电子商务收入和上周的前 10 笔订单。”
- “创建一个德国客户的细分，并计算匹配的数量。”
- “草拟一个 SMS 广播发送到 ‘VIP’ 列表 — 但在您确认之前不要发送。”
工具会自动从 ActiveCampaign 的规范中生成，并分为 🟢 只读、🟡 写入和 🔴 破坏性 — 因此，行为良好的主机可以对每个组进行不同的处理。
## 它是如何工作的
```
Claude / Cursor / 任意 MCP 客户端 ──MCP──► 此服务器 ──HTTPS──► ActiveCampaign API（您的账户）
```
服务器解析捆绑的 OpenAPI 定义为 MCP 工具（解析 `$ref` 并防止递归模式），为每个工具添加一个精选的安全类别，并注入您的 `Api-Token` 头部到每个输出请求。您的令牌保留在服务器的环境中 — 模型永远不会看到或处理它。
## 要求
- **具有 API 访问权限的 ActiveCampaign 账户** — 您的 **API URL** 和 **API 令牌** 来自 **设置 → 开发者**。请参阅 [获取您的 API 凭证](#获取您的-api-凭证)。
- **Docker** （适用于 Docker Desktop 在 macOS/Windows 上）以进行快速启动 — 或 **Node.js ≥ 18** 以 [从源代码运行](#从源代码运行_stdio 无 Docker)。
## 快速入门（Docker）
**1. 添加您的凭证。** 复制示例配置并填写：
```bash
cp .env.example .env
# 编辑 .env → 设置 ACTIVECAMPAIGN_API_URL 和 ACTIVECAMPAIGN_API_TOKEN
# → 设置 MCP_SHARED_TOKEN 为一个长随机字符串，如果可访问范围超出 localhost
```
**2. 启动服务器：
```bash
docker compose up -d --build
```
捆绑的 `docker-compose.yml` 只绑定到 `127.0.0.1:8765`，因此服务器仅从您的机器可访问，而不可访问网络。
**3. 确认它正在运行：
```bash
curl -s http://localhost:8765/health
# → {"status":"ok","server":"activecampaign-mcp","tools":325}
```
**4. 连接您的 MCP 客户端。** MCP 端点是 `http://localhost:8765/mcp`。
- **Claude Desktop** — 添加一个 **自定义连接器**（设置 → 连接器）指向 URL，或使用
[`mcp-remote`](https://www.npmjs.com/package/mcp-remote）桥接它。添加此项到
`mcpServers` 在您的配置中，然后完全退出并重新打开应用程序：
```json
{
"mcpServers": {
"activecampaign": {
"command": "npx",
"args": [
"mcp-remote",
"http://localhost:8765/mcp",
"--header", "Authorization: Bearer YOUR_MCP_SHARED_TOKEN"
]
}
}
}
```
（如果您留下了 `MCP_SHARED_TOKEN` 空，请删除 `--header` 行。）
- **Claude Code** — 一个命令：
```bash
claude mcp add --transport http activecampaign http://localhost:8765/mcp
```
- **Claude Cowork** — 与 Claude Code 共享 Claude Code 的 MCP 配置，因此上述命令使工具在那里也可用。
### 更喜欢预构建的镜像？
每次推送到 `main` 都会将一个准备好的镜像发布到 GitHub 容器注册表，因此您可以跳过本地构建：
```bash
docker run -d --name activecampaign-mcp -p 127.0.0.1:8765:8765 --env-file .env \
ghcr.io/ohneben/activecampaign-mcp:latest
```
## 获取您的 API 凭证
1. 登录 ActiveCampaign 并打开 **设置 → 开发者**。
2. 复制您的 **API URL** → `ACTIVECAMPAIGN_API_URL`。它类似于
`https://your-account.api-us1.com/api/3`。**使用显示的准确 URL** — 所有帐户不在 `api-us1`，自定义域名不同。
3. 复制您的 **API 密钥** → `ACTIVECAMPAIGN_API_TOKEN`。
将两者放入 `.env`。服务器在每个请求中注入令牌，因此您的
助手永远不会看到它。
## 配置
一切都设置在 `.env`（从 `.env.example` 复制而来）：
| 变量 | 必需 | 默认值 | 描述 |
|---|---|---|---|
| `ACTIVECAMPAIGN_API_URL` | ✅ | — | 您的帐户的 API URL，包括 `/api/3` |
| `ACTIVECAMPAIGN_API_TOKEN` | ✅ | — | 您的 API 令牌（`Api-Token` 头部） |
| `MCP_TRANSPORT` | — | `stdio` | `stdio` 或 `http`（Docker 镜像默认为 `http`) |
| `PORT` | — | `8765` | HTTP 监听端口 |
| `HOST` | — | `0.0.0.0` | HTTP 绑定地址 |
| `MCP_HTTP_PATH` | — | `/mcp` | HTTP MCP 路线 |
| `MCP_SHARED_TOKEN` | — | _(关闭) | 要求 `/mcp` 的 `Authorization: Bearer <token>` |
| `ACTIVECAMPAIGN_MAX_REQUESTS` | — | `4` | 客户端请求数/窗口（`0` 禁用限流） |
| `ACTIVECAMPAIGN_RATE_WINDOW_MS` | — | `1000` | 速率限制窗口毫秒（|default: 4 req/s) |
| `ACTIVECAMPAIGN_MAX_RETRIES` | — | `3` | `429` / `5xx` / 网络错误时的重试次数 |
| `ACTIVECAMPAIGN_TIMEOUT_MS` | — | `30000` | 尝试超时时间 |
| `ACTIVECAMPAIGN_READ_ONLY` | — | `false` | 仅公开 🟢 只读工具 |
| `ACTIVECAMPAIGN_INCLUDE_GROUPS` | — | _(all)_ | 仅公开这些资源组（逗号分隔） |
| `ACTIVECAMPAIGN_EXCLUDE_GROUPS` | — | _(none)_ | 隐藏这些资源组 |
| `ACTIVECAMPAIGN_ENABLE_GRAPHQL` | — | `true` | 公开 GraphQL 直通工具 |
| `ACTIVECAMPAIGN_GRAPHQL_URL` | — | _(derived)_ | 重写 GraphQL 端点 |
| `ACTIVECAMPAIGN_MAX_RESPONSE_CHARS` | — | `0` | 截断超过 N 个字符的响应（`0` = 永不） |
| `ACTIVECAMPAIGN_SPEC_DIR` | — | _(bundled)_ | 从不同的目录加载 OpenAPI 文件 |
更改 `.env` 后，请使用 `docker compose up -d --force-recreate` 重启。
在 `claude_desktop_config.json` 中运行 `npm run list-tools`（无需凭证）以打印完整的工具目录、按类别统计和可筛选的资源组密钥。
## 工具安全类别
每个工具的描述以以下标志之一开头，并带有匹配的
[MCP 注释](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations)：
| 标志 | 计数 | `readOnlyHint` | `destructiveHint` | 含义 |
|---|:---:|:---:|:---:|---|
| 🟢 **只读** | 155 | `true` | `false` | `GET` — 仅获取数据。安全。 |
| 🟢 **只读 · 查询** | 7 | `true` | `false` | 一种 `POST` 查询/报告（分段匹配，指标导出）— 不更改数据。 |
| 🟡 **写入 · 创建数据** | 51 | `false` | `false` | `POST` — 创建记录（非幂等；可能重复）。 |
| 🟡 **写入 · 创建或更新** | 1 | `false` | `false` | 幂等更新（`contact sync`）。 |
| 🟡 **写入 · 更新数据** | 52 | `false` | `false` | `PUT` / `PATCH` — 修改记录。 |
| 🟡 **写入 · 链接记录** | 6 | `false` | `false` | 关联记录（标记联系人，添加到列表/自动化）。可逆。 |
| 🟡 **写入 · 取消链接记录** | 5 | `false` | `false` | 删除关联（取消标记，移除列表）。可逆。 |
| 🟡 **写入 · 发送消息** | 3 | `false` | `false` | 发送/安排 SMS 或 WhatsApp 消息。 |
| 🟡 **GraphQL** | 1 | `false` | `false` | 任意 GraphQL 文档（可能包含突变）。 |
| 🔴 **破坏性 · 删除数据** | 42 | `false` | `true` | `DELETE` — 删除记录。需确认。 |
| 🔴 **破坏性 · 批量删除** | 2 | `false` | `true` | 一次删除多个记录。需确认。 |
这是 **162 只读 · 119 写入 · 44 破坏性 = 325 工具**。尊重注释的主机（包括 Claude）可以为
`destructiveHint` 工具要求确认并自动信任 `readOnlyHint` 工具。如果您想进一步限制，请设置
`ACTIVECAMPAIGN_READ_ONLY=true` 以仅公开 162 个只读工具。
<details>
<summary><strong>按区域覆盖（🟢 只读 / 🟡 写入 / 🔴 破坏性）</strong></summary>
| 区域 | 🟢 只读 | 🟡 写入 | 🔴 删除 | 工具 |
|---|:---:|:---:|:---:|:---:|
| 自定义字段和对象 | 18 | 25 | 9 | **52** |
| 交易和管道 | 19 | 23 | 9 | **51** |
| 联系人 | 30 | 11 | 2 | **43** |
| 活动和消息 | 15 | 10 | 4 | **29** |
| 管理和交付 | 12 | 8 | 6 | **26** |
| 账户 | 8 | 13 | 4 | **25** |
| 分段 | 16 | 3 | 1 | **20** |
| 电子商务（深入数据） | 9 | 6 | 3 | **18** |
| SMS | 12 | 4 | 1 | **17** |
| 列表、标签和表单 | 8 | 5 | 2 | **15** |
| 站点和事件跟踪 | 7 | 5 | 2 | **14** |
| WhatsApp | 7 | 5 | 1 | **13** |
| 自动化 | 1 | 0 | 0 | **1** |
| GraphQL 直通 | — | 1 | — | **1** |
| **总数** | **162** | **119** | **44** | **325** |
</details>
## 从源代码运行（stdio，无 Docker）
如果您更喜欢经典的 stdio 模式，请为 Claude Desktop 构建它：
```bash
npm install
npm run build
```
然后在 `claude_desktop_config.json` 中将编译后的入口点指向
`claude_desktop_config.json`:
```json
{
"mcpServers": {
"activecampaign": {
"command": "node",
"args": ["/ABSOLUTE/PATH/ActiveCampaign-MCP/dist/index.js"],
"env": {
"MCP_TRANSPORT": "stdio",
"ACTIVECAMPAIGN_API_URL": "https://your-account.api-us1.com/api/3",
"ACTIVECAMPAIGN_API_TOKEN": "your-api-token"
}
}
}
}
```
## 保持规范最新
`spec/` 下的文件是工具的真实来源：
| 文件 | API | 认证头部 |
|---|---|---|
| `v3.json` | 核心 v3 REST API | `Api-Token` |
| `sms.json` | SMS 广播 API | `Api-Token` |
| `whatsapp.json` | WhatsApp 通道 API | `Token`（也发送 `Api-Token`） |
| `segments-crud.json`、`segments-match-one.json`、`segments-match-all-some.json` | 异步分段 API | `Api-Token` |
要刷新新的 API 版本，请将更新的 OpenAPI JSON 文件放入原位（或
将 `ACTIVECAMPAIGN_SPEC_DIR` 指向使用相同文件名的目录），然后
重建。新的路径将自动成为新的工具 — 无需代码更改。
## 开发
```bash
npm install
npm run build # 编译 TypeScript → dist/
npm test # 运行 Vitest 套件
npm run list-tools # 打印工具目录（无需凭证）
```
CI 每推送都会在 Node 20 和 22 上构建和测试；推送到 `main` 也会
发布 Docker 镜像到 GitHub 容器注册表。
## 注释和约定
- **传输方式**：`MCP_TRANSPORT=stdio`（默认）适用于本地启动器；
`MCP_TRANSPORT=http` 适用于始终在线的 Streamable-HTTP 服务器（Docker 镜像运行）。
- **分页/排序/筛选**：列表工具接受 `limit`（最大 100）、`offset`、
`orders`（`{"email":"ASC"}`）和 `filters`（`{"name":"ecom"}`）。对于非常大的
联系人导出，ActiveCampaign 建议 `orders={"id":"ASC"}` + `id_greater`。
- **速率限制**：ActiveCampaign 允许每个帐户每秒 5 个请求（在所有密钥中共享
跨越）；服务器在 `ACTIVECAMPAIGN_MAX_REQUESTS` 每
`ACTIVECAMPAIGN_RATE_WINDOW_MS`（默认为 4 / 1 秒）进行自我限制，并在收到 `429` 时重试，遵循 `Retry-After`。
- **请求正文**：写入工具采用 `body` 参数；其架构从规范中解析并显示给模型（例如，`create-contact` 需要
`{"contact": {…}}`）。
## 安全
- 您的 API 令牌仅存储在 `.env` 中，该文件被 git 忽略。**永远不要提交真正的
机密。** 如果令牌泄露，请在 **ActiveCampaign → 设置 → 开发者** 中轮换它。
- 默认情况下，HTTP 端点是未经身份验证的（在 localhost 上没问题）。要将其公开到您的机器之外，请设置 `MCP_SHARED_TOKEN` 并将其作为
`Authorization: Bearer <token>` 头部发送 — 理想情况下使用 TLS。
- 删除和 **发送**（SMS/WhatsApp）工具带有正确的注释，以便行为良好的主机在操作之前提示 — 保留此确认，或在
`ACTIVECAMPAIGN_READ_ONLY=true` 模式下运行。
参见 [SECURITY.md](./SECURITY.md) 以获取完整的策略和如何报告漏洞。
## 致谢和许可证
ActiveCampaign 的非官方社区集成；不隶属于或获得 ActiveCampaign 认可。
构建在 [Model Context Protocol](https://modelcontextprotocol.io) 之上。工具从 ActiveCampaign 的公共 OpenAPI 定义中生成。
根据 [MIT License](./LICENSE.md) 许可。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器