ActiveCampaign

ohneben 的 ActiveCampaign MCP

---

许可证与检查

MCP 注册目录

这是目前功能最全面的 ActiveCampaign MCP 服务。 使用 Claude、Cursor 或任何其他 MCP 客户端， 即可通过自然语言管理整个 ActiveCampaign 账户。

此 Model Context Protocol 服务开放了 完整的 ActiveCampaign 账户 API — 约 325 个工具，涵盖 v3 REST API，以及 SMS、WhatsApp 和异步 Segments API，直接根据 ActiveCampaign 自己的 OpenAPI 定义生成。每个工具都经过安全类别标记 （🟢 只读 / 🟡 写入 / 🔴 破坏性），让助手在调用操作之前了解其作用。服务可通过 stdio（Claude Desktop 和其他本地启动器）或 Streamable HTTP（在 Docker 中托管）运行，并配备重试机制、针对 ActiveCampaign 每秒 5 次请求上限调优的客户端限流，以及请求超时设置，可稳定应对实际账户。

为什么你会需要它

有些 MCP 服务只是转发 API 的一部分。这个服务旨在做到可安全交给大模型使用、功能完整，并且易于实际运行：

你将获得什么	为什么重要
约 325 个工具 — 完整的账户 API	全面覆盖联系人、交易、账户、列表、标签、自定义字段和对象、电商（深度数据）、营销活动、消息、自动化、细分群组、Webhook、任务、日历、网站/事件跟踪、SMS 和 WhatsApp——没有挑挑拣拣，也没有遗漏。其他服务通常只支持约 60 个工具。
精心设计的安全类别 🟢 / 🟡 / 🔴	不会天真地认为“GET = 安全”：contact sync 会标记为插入或更新，细分群组匹配的 POST 会标记为只读查询，为联系人添加标签会标记为关联，而 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 Ecommerce GraphQL API 的工具，可通过一次往返请求精确指定所需字段。
两种传输方式：stdio 和 Streamable HTTP	可在 Claude Desktop 中本地使用，也可运行一个常驻服务，让任意数量的 MCP 客户端通过 HTTP 访问。
Docker + docker-compose、健康检查、自动重启	开箱即用的生产级部署：运行 docker compose up 后，服务就会持续运行。
HTTP 端点支持可选的 Bearer 令牌认证	只要服务可从 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 + compose + 健康检查	✅	不适用	❌	❌	❌
精选的 🟢 / 🟡 / 🔴 安全类别	✅	➖	➖ 部分支持	➖	不适用
readOnlyHint / destructiveHint	✅	➖	➖	➖	➖
只读模式 + 分组筛选	✅	❌	❌	❌	始终只读
速率限制 + 自动重试（429/5xx）	✅	➖	❌	➖	❌
语言	TypeScript	—	TypeScript	Python	Java
许可证	MIT	专有	MIT	MIT	MIT

_{✅ = 是 · ➖ = 部分支持 / 未注明 · ❌ = 否。根据各项目公开文档整理；这是一个非官方项目，与 ActiveCampaign 或表中列出的项目均无关联。工具数量为近似值，会随 API 演进而变化。}

简而言之：官方远程 MCP 是很好的托管入门方案，但运行在 ActiveCampaign 的云端，且只涵盖精选的 API 子集。社区服务很可靠，但最多只有约 60 个核心 CRM 工具，且仅支持 stdio，没有部署方案。本服务提供完整的账户 API、两种传输方式、Docker 部署和安全防护措施——可自托管，使用你自己的令牌，采用 MIT 许可证。

可以做什么

连接后，可以向助手提出以下请求：

• “查找联系人 [email protected]，并显示她的标签、列表和近期活动。”
• “在‘Sales’销售流程的‘Qualified’阶段，为 Acme Corp 创建一笔金额为 $12,000 的交易。”
• “列出本月添加、打开了上一场营销活动，但尚未添加‘engaged’标签的联系人。”
• “为列表 5 中的每位联系人添加‘webinar-2026’标签。”
• “显示电商总收入和上周金额最高的 10 笔订单。”
• “创建一个包含德国客户的细分，并统计符合条件的人数。”
• “为‘VIP’列表拟一条 SMS 群发消息——但在我确认之前不要发送。”

工具会根据 ActiveCampaign 的规范自动生成，并分为 🟢 只读、🟡 写入和 🔴 破坏性操作三类，这样行为规范的宿主就可以区别对待各组工具。

工作原理

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

服务会将打包的 OpenAPI 定义解析为 MCP 工具（解析 $ref 并防止递归架构），为每个工具标注精选的安全类别，并在每个发出的请求中注入 Api-Token 标头。令牌保存在服务的环境中——模型看不到也不会处理它。

要求

• 拥有 API 访问权限的 ActiveCampaign 账户——从Settings → Developer 获取你的 API URL 和 API token。请参阅获取 API 凭据。
• 按照下方快速入门操作需要 Docker（macOS/Windows 上使用 Docker Desktop）；或者需要 Node.js ≥ 18，以便从源代码运行。

快速开始（Docker）

1. 添加凭据。 复制示例配置并填写：

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. 启动服务：

docker compose up -d --build

随附的 docker-compose.yml 仅绑定到 127.0.0.1:8765，因此服务可从你的计算机访问，但无法从网络访问。

3. 确认服务正在运行：

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

4. 连接 MCP 客户端。 MCP 端点为 http://localhost:8765/mcp。

• Claude Desktop — 添加一个指向该 URL 的自定义连接器（Settings → Connectors），或使用 mcp-remote 在本地桥接。在配置的 mcpServers 下添加以下内容，然后完全退出并重新打开应用：

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

  （如果将 MCP_AUTH_TOKEN 留空，请删除 --header 行。）

• Claude Code — 只需一条命令：

  claude mcp add --transport http activecampaign http://localhost:8765/mcp
  

• Claude Cowork — 与 Claude Code 共用 MCP 配置，因此运行上述命令后，这些工具也会在其中可用。

更倾向于使用预构建镜像？

每次推送到 main 时，都会向 GitHub Container Registry 发布一个可直接运行的镜像，因此你可以完全跳过本地构建：

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 并打开 Settings → Developer。
2. 复制你的 API URL → ACTIVECAMPAIGN_API_URL。格式类似 https://your-account.api-us1.com/api/3。请使用显示的确切 URL — 并非所有账户都使用 api-us1，自定义域名也各不相同。
3. 复制你的 API Key → 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_AUTH_TOKEN	—	(关闭)	要求访问 /mcp 时提供 Authorization: Bearer <token>
ACTIVECAMPAIGN_MAX_REQUESTS	—	4	每个时间窗口内客户端请求数（0 表示禁用限流）
ACTIVECAMPAIGN_RATE_WINDOW_MS	—	1000	限流时间窗口，单位为 ms（默认：4 req/s）
ACTIVECAMPAIGN_MAX_RETRIES	—	3	遇到 429 / 5xx / 网络错误时的重试次数
ACTIVECAMPAIGN_TIMEOUT_MS	—	30000	每次尝试的请求超时时间
ACTIVECAMPAIGN_READ_ONLY	—	false	仅公开 🟢 只读工具
ACTIVECAMPAIGN_INCLUDE_GROUPS	—	(全部)	仅公开这些资源组（以逗号分隔）
ACTIVECAMPAIGN_EXCLUDE_GROUPS	—	(无)	隐藏这些资源组
ACTIVECAMPAIGN_ENABLE_GRAPHQL	—	true	公开 Ecommerce GraphQL 透传工具
ACTIVECAMPAIGN_GRAPHQL_URL	—	(自动推导)	覆盖 GraphQL 端点
ACTIVECAMPAIGN_MAX_RESPONSE_CHARS	—	0	截断超过 N 个字符的响应（0 = 从不截断）
ACTIVECAMPAIGN_SPEC_DIR	—	(随附目录)	从其他目录加载 OpenAPI 文件

更改 .env 后，运行 docker compose up -d --force-recreate 重新加载。

运行 npm run list-tools（无需凭据）即可打印完整目录、各类别的数量，以及可用于筛选的资源组键列表。

工具安全类别

每个工具的描述都以以下横幅之一开头，并带有对应的 MCP 注解：

横幅	数量	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 个只读工具。

各领域覆盖情况（🟢 读取 / 🟡 写入 / 🔴 破坏性操作）

领域	🟢 读取	🟡 写入	🔴 删除	工具
自定义字段与对象	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

从源代码运行（stdio，无 Docker）

更喜欢在 Claude Desktop 中使用经典的 stdio 模式？在本地构建：

npm install
npm run build

然后在 claude_desktop_config.json 中，将 Claude Desktop 指向已编译的入口点：

{
  "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 指向包含相同文件名的目录），然后重新构建。新路径会自动成为新工具，无需更改代码。

开发

npm install
npm run build      # compile TypeScript → dist/
npm test           # run the Vitest suite
npm run list-tools # print the categorized tool catalog (no credentials needed)

CI 会在 Node 20 和 22 环境下构建并测试每次推送；推送到 main 时，还会将 Docker 镜像发布到 GitHub Container Registry。

说明与约定

• 传输方式：本地启动器使用 MCP_TRANSPORT=stdio（默认值）； Docker 镜像运行的常驻 Streamable-HTTP 服务使用 MCP_TRANSPORT=http。
• 分页 / 排序 / 筛选：列表工具接受 limit（最大值为 100）、offset、 orders（{"email":"ASC"}）和 filters（{"name":"ecom"}）。对于非常大的 联系人导出，ActiveCampaign 建议使用 orders={"id":"ASC"} + id_greater。
• 速率限制：ActiveCampaign 允许每个账户每秒发送 5 个请求（所有密钥共享此限制）；服务会将请求速率限制在 ACTIVECAMPAIGN_MAX_REQUESTS / ACTIVECAMPAIGN_RATE_WINDOW_MS（默认为 1 秒 4 个请求），并重试仍收到的任何 429 响应，同时遵循 Retry-After。
• 请求正文：写入工具接受 body 参数；其架构根据规范解析并展示给模型（例如，create-contact 需要 {"contact": {…}}）。

安全

• 你的 API 令牌仅存储在 .env 中，该文件已加入 git 忽略列表。**切勿提交真实 密钥。**此令牌拥有账户的完全访问权限；如果泄露，请在 ActiveCampaign → Settings → Developer 中轮换令牌。
• HTTP 端点默认不需要身份验证（在 localhost 上使用没有问题）。若要将其开放给其他设备访问，请设置 MCP_AUTH_TOKEN，并通过 Authorization: Bearer <token> 标头发送令牌——最好在 TLS 后面部署。
• 删除和发送（SMS/WhatsApp）工具带有相应注释，以便行为良好的宿主在执行前进行确认——请保留此确认，或在 ACTIVECAMPAIGN_READ_ONLY=true 模式下运行。

完整政策及漏洞报告方式请参阅 SECURITY.md。

致谢与许可

这是一个非官方的社区集成项目，适用于 ActiveCampaign；与 ActiveCampaign 无关联，也未获其认可。基于 Model Context Protocol 构建。 工具根据 ActiveCampaign 的公开 OpenAPI 定义生成。根据 MIT License 授权。