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 的問題板塊與我們聯繫

---