Activecampaign MCP Server

🚀 ActiveCampaign MCP 服务器

这是一个 MCP（模型上下文协议）服务器，用于与 ActiveCampaign API 集成。借助对 AI 友好的工具，它允许对联系人及跟踪事件进行查询和分析。

🚀 快速开始

在使用此服务器之前，请确保满足以下安装要求并完成相应的安装步骤。

安装前的准备

• Node.js 18 或更高版本
• NPM 或 PNPM
• 拥有可访问 API 的 ActiveCampaign 账户

安装步骤

1. 克隆仓库

git clone https://github.com/mmarqueti/activecampaign-mcp-server.git
cd activecampaign-mcp-server

2. 安装依赖项

# 使用 npm
npm install

# 使用 pnpm
pnpm install

3. 配置环境变量

cp .env.example .env

编辑 .env 文件并填入你的凭证信息：

ACTIVECAMPAIGN_API_URL=https://seuaccount.api-us1.com
ACTIVECAMPAIGN_API_KEY=sua-api-key-aqui

4. 编译项目

# 使用 npm
npm run build

# 使用 pnpm
pnpm build

✨ 主要特性

🔍 联系人管理

• 按邮箱搜索：使用邮箱地址查找联系人
• 按 ID 搜索：通过 ID 获取特定联系人
• 高级搜索：使用过滤器和分页功能搜索联系人
• 丰富的数据：包含自定义字段、标签和列表

📊 跟踪与分析

• 事件日志：访问每个联系人的完整事件历史记录
• 高级过滤：按事件类型、日期和其他标准进行过滤
• 按邮箱搜索：仅使用联系人的邮箱获取跟踪日志
• 结构化数据：事件包含时间戳、描述和元数据

🛠️ 支持的事件类型

• 邮件相关：open（打开）、click（点击）、sent（发送）、bounce（退回）、reply（回复）、forward（转发）
• 管理类：subscribe（订阅）、unsubscribe（取消订阅）、update（更新）
• 销售类：deal_add（添加交易）、deal_update（更新交易）、deal_delete（删除交易）
• 生产力类：note_add（添加备注）、task_add（添加任务）
• 自动化类：automation_start（自动化开始）、automation_complete（自动化完成）

💻 使用示例

启动服务器

# 开发模式
npm run dev

# 生产模式
npm start

在 Claude Desktop 中进行配置

若要在 Claude Desktop 中使用此 MCP 服务器，需要在其配置文件中进行如下设置：

⚠️ 重要提示

此功能要求 Claude Desktop 版本为 0.7.0 或更高，且支持 MCP。

1. 找到配置文件

macOS 系统：

~/Library/Application Support/Claude/claude_desktop_config.json

Windows 系统：

%APPDATA%\Claude\claude_desktop_config.json

2. 添加服务器配置

编辑 claude_desktop_config.json 文件并添加以下内容：

{
  "mcpServers": {
    "activecampaign": {
      "command": "node",
      "args": ["/caminho/para/seu/projeto/dist/index.js"],
      "env": {
        "ACTIVECAMPAIGN_API_URL": "https://seuaccount.api-us1.com",
        "ACTIVECAMPAIGN_API_KEY": "sua-api-key-aqui"
      }
    }
  }
}

完整路径示例：

{
  "mcpServers": {
    "activecampaign": {
      "command": "node",
      "args": ["/Users/seunome/projetos/activecampaign-mcp-server/dist/index.js"],
      "env": {
        "ACTIVECAMPAIGN_API_URL": "https://seuaccount.api-us1.com",
        "ACTIVECAMPAIGN_API_KEY": "abc123def456ghi789"
      }
    }
  }
}

3. 编译项目

确保项目已编译：

# 使用 npm
npm run build

# 推荐使用 pnpm
pnpm build

4. 测试服务器（可选）

在配置到 Claude Desktop 之前，你可以测试服务器是否正常工作：

# 使用 MCP 检查器进行测试
pnpm inspect

# 或者直接测试
node dist/index.js

5. 重启 Claude Desktop

完全关闭并重新打开 Claude Desktop，以加载新的配置。

6. 验证是否生效

在 Claude Desktop 中，你可以使用以下命令：

• "查找邮箱为 usuario@exemplo.com 的联系人"
• "显示 ID 为 123 的联系人的跟踪事件"
• "搜索姓名为 João Silva 的联系人"

🚨 故障排除

若工具未显示：

1. 检查路径：确保 dist/index.js 的路径正确
2. 检查编译情况：再次执行 npm run build
3. 检查凭证信息：确认 API URL 和密钥是否正确
4. 查看日志：查看 Claude Desktop 的日志以查找错误
5. 完全重启：通过活动监视器/任务管理器关闭 Claude Desktop

使用系统环境变量的替代配置：

{
  "mcpServers": {
    "activecampaign": {
      "command": "node",
      "args": ["/caminho/para/seu/projeto/dist/index.js"]
    }
  }
}

在这种情况下，需在系统中设置环境变量：

export ACTIVECAMPAIGN_API_URL="https://seuaccount.api-us1.com"
export ACTIVECAMPAIGN_API_KEY="sua-api-key-aqui"

🧪 测试工具

配置完成后，你可以直接在 Claude Desktop 中测试这些工具：

命令示例：

🔍 查找联系人：
"在 ActiveCampaign 中查找邮箱为 john@exemplo.com 的联系人信息"

📊 参与度分析：
"显示 ID 为 123 的联系人在过去 30 天内的邮件事件"

🔍 高级搜索：
"搜索姓名中包含 'CEO' 的所有联系人，并显示其完整信息"

📈 活动报告：
"分析 maria@empresa.com 在过去 3 个月内的参与行为"

可用工具

1. 按邮箱查找联系人

{
  "name": "get_contact_by_email",
  "arguments": {
    "email": "usuario@exemplo.com"
  }
}

2. 按 ID 查找联系人

{
  "name": "get_contact_by_id",
  "arguments": {
    "contactId": "123"
  }
}

3. 搜索联系人

{
  "name": "search_contacts",
  "arguments": {
    "query": "João Silva",
    "limit": 10
  }
}

4. 按 ID 获取跟踪日志

{
  "name": "get_contact_tracking_logs",
  "arguments": {
    "contactId": "123",
    "limit": 50,
    "offset": 0,
    "eventType": "open",
    "dateRange": {
      "start": "2024-01-01",
      "end": "2024-12-31"
    }
  }
}

5. 按邮箱获取跟踪日志

{
  "name": "get_contact_tracking_logs_by_email",
  "arguments": {
    "email": "usuario@exemplo.com",
    "limit": 100,
    "eventType": "click"
  }
}

📚 详细文档

项目结构

src/
├── index.ts              # 主 MCP 服务器
├── types/
│   └── index.ts          # TypeScript 接口和类型
└── tools/
    ├── index.ts          # 工具导出
    ├── contacts.ts       # 联系人工具
    └── tracking.ts       # 跟踪工具

架构特点

• 模块化：每个工具集都位于独立的文件中
• 类型化：所有数据都使用 TypeScript 接口
• 可扩展：便于添加新工具
• 可测试：类相互隔离，便于进行测试

响应示例

联系人数据

{
  "id": "123",
  "email": "usuario@exemplo.com",
  "firstName": "João",
  "lastName": "Silva",
  "phone": "+55 11 99999-9999",
  "fieldValues": [
    {
      "field": "Empresa",
      "value": "Exemplo Corp"
    }
  ],
  "tags": ["Cliente VIP", "Newsletter"],
  "lists": [
    {
      "list": "Newsletter Mensal",
      "status": "active"
    }
  ],
  "cdate": "2024-01-15T10:30:00Z",
  "udate": "2024-01-20T14:45:00Z"
}

跟踪日志

{
  "summary": {
    "total": 25,
    "count": 25,
    "limit": 100,
    "offset": 0,
    "eventTypes": {
      "open": 15,
      "click": 8,
      "sent": 2
    }
  },
  "events": [
    {
      "id": "456",
      "type": "open",
      "timestamp": "2024-01-15T10:30:00-03:00",
      "date": "2024-01-15T13:30:00.000Z",
      "contact": "123",
      "subscriberId": "123",
      "hash": "abc123",
      "description": "Email foi aberto",
      "campaign": {
        "id": "789",
        "name": "Newsletter Janeiro"
      }
    }
  ]
}

🤝 贡献代码

我们非常欢迎你的贡献！若要贡献代码，请按以下步骤操作：

1. Fork 此项目
2. 创建 一个新的功能分支 (git checkout -b feature/nova-funcionalidade)
3. 提交 你的更改 (git commit -m '添加新功能')
4. 推送 到该分支 (git push origin feature/nova-funcionalidade)
5. 发起 一个 Pull Request

开发相关命令

# 安装依赖项
pnpm install

# 以开发模式运行
pnpm dev

# 运行测试
pnpm test

# 检查代码规范
pnpm lint

# 编译生产版本
pnpm build

📄 许可证

本项目采用 MIT 许可证。有关详细信息，请参阅 LICENSE 文件。

🔗 相关链接

• ActiveCampaign API 文档
• 模型上下文协议
• 问题反馈

📞 支持与帮助

若你遇到任何问题或有疑问，请按以下步骤操作：

1. 检查是否存在 类似问题
2. 创建一个新的问题并详细描述问题
3. 通过 GitHub 的问题板块与我们联系