Activecampaign MCP Server

🚀 ActiveCampaign MCP Server

ActiveCampaignのAPIと統合するためのMCP（Model Context Protocol）サーバーです。AIに適したツールを通じて、連絡先やトラッキングイベントの照会と分析を可能にします。

✨ 主な機能

🔍 連絡先管理

• メールアドレスで検索：メールアドレスを使用して連絡先を見つけます。
• 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

🚀 インストール

前提条件

• Node.js 18以上
• NPMまたはPNPM
• ActiveCampaignのAPIにアクセスできるアカウント

インストール手順

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

⚙️ 設定

ActiveCampaignの認証情報を取得する

1. ActiveCampaignのアカウントにアクセスします。
2. Settings > Developerに移動します。
3. API URLとAPI Keyをコピーします。
4. コピーした認証情報を.envファイルに貼り付けます。

環境変数

🔧 使用例

サーバーを起動する

# 開発モード
npm run dev

# 本番モード
npm start

Claude Desktopでの設定

このMCPサーバーをClaude Desktopで使用するには、Claudeの設定ファイルに設定する必要があります。

⚠️ 重要な注意

この機能には、MCPをサポートするClaude Desktopバージョン0.7.0以上が必要です。

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. 完全に再起動する：Activity Monitor/Task Managerを使用して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 'Adiciona nova funcionalidade')。
4. ブランチにプッシュします (git push origin feature/nova-funcionalidade)。
5. プルリクエストを作成します。

開発

# 依存関係をインストールする
pnpm install

# 開発モードで実行する
pnpm dev

# テストを実行する
pnpm test

# リンティングを確認する
pnpm lint

# 本番用にビルドする
pnpm build

📝 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細についてはLICENSEファイルを参照してください。

🔗 有用なリンク

• ActiveCampaign APIドキュメント
• Model Context Protocol
• Issues

📞 サポート

問題が発生した場合や質問がある場合は：

1. issueを確認して、似たような問題がないかを確認します。
2. 問題の詳細を記載した新しいissueを作成します。
3. GitHubのissueを通じて連絡してください。