Activecampaign MCP Server

🚀 ActiveCampaign MCP Server

An MCP (Model Context Protocol) server for integrating with the ActiveCampaign API, enabling queries and analyses of contacts and tracking events through AI-friendly tools.

✨ Features

🔍 Contact Management

• Search by email: Find contacts using the email address.
• Search by ID: Retrieve specific contacts by ID.
• Advanced search: Search for contacts with filters and pagination.
• Enriched data: Includes custom fields, tags, and lists.

📊 Tracking and Analytics

• Event logs: Access the complete history of events per contact.
• Advanced filters: Filter by event type, date, and other criteria.
• Search by email: Obtain tracking logs using only the contact's email.
• Structured data: Events formatted with timestamps, descriptions, and metadata.

🛠️ Supported Event Types

• Email: open, click, sent, bounce, reply, forward
• Management: subscribe, unsubscribe, update
• Sales: deal_add, deal_update, deal_delete
• Productivity: note_add, task_add
• Automation: automation_start, automation_complete

🚀 Installation

Prerequisites

• Node.js 18 or higher
• NPM or PNPM
• An ActiveCampaign account with API access

Installation Steps

1. Clone the repository

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

2. Install the dependencies

# With npm
npm install

# With pnpm
pnpm install

3. Configure the environment variables

cp .env.example .env

Edit the .env file with your credentials:

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

4. Compile the project

# With npm
npm run build

# With pnpm
pnpm build

⚙️ Configuration

Obtaining ActiveCampaign Credentials

1. Access your ActiveCampaign account.
2. Go to Settings > Developer.
3. Copy your API URL and API Key.
4. Paste the credentials into the .env file.

Environment Variables

💻 Usage Examples

Starting the Server

# Development mode
npm run dev

# Production mode
npm start

Configuring in Claude Desktop

To use this MCP server with Claude Desktop, you need to configure it in the Claude configuration file:

⚠️ Important Note

This feature requires Claude Desktop version 0.7.0 or higher with MCP support.

1. Locate the configuration file

macOS:

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

Windows:

%APPDATA%\Claude\claude_desktop_config.json

2. Add the server configuration

Edit the claude_desktop_config.json file and add:

{
  "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"
      }
    }
  }
}

Example with full path:

{
  "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. Compile the project

Make sure the project is compiled:

# With npm
npm run build

# With pnpm (recommended)
pnpm build

4. Test the server (optional)

Before configuring in Claude Desktop, you can test if the server is working:

# Test with MCP inspector
pnpm inspect

# Or test directly
node dist/index.js

5. Restart Claude Desktop

Completely close Claude Desktop and open it again to load the new configuration.

6. Check if it works

In Claude Desktop, you should be able to use commands like:

• "Search for the contact with email usuario@exemplo.com"
• "Show the tracking events of contact ID 123"
• "Search for contacts with the name João Silva"

🚨 Troubleshooting

If the tools do not appear:

1. Check the path: Make sure the path to dist/index.js is correct.
2. Check the compilation: Run npm run build again.
3. Check the credentials: Confirm that the API URL and Key are correct.
4. Check the logs: Look at the Claude Desktop logs for errors.
5. Restart completely: Close Claude Desktop through the Activity Monitor/Task Manager.

Alternative configuration with system environment variables:

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

In this case, set the variables in your system:

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

🧪 Testing the Tools

Once configured, you can test the tools directly in Claude Desktop:

Example commands:

🔍 Search for a contact:
"Search for information about the contact john@exemplo.com in ActiveCampaign"

📊 Engagement analysis:
"Show the email events of the last 30 days for contact ID 123"

🔍 Advanced search:
"Search for all contacts with 'CEO' in their name and show me their complete information"

📈 Activity report:
"Analyze the engagement behavior of contact maria@empresa.com in the last 3 months"

Available Tools

1. Search for a Contact by Email

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

2. Search for a Contact by ID

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

3. Search for Contacts

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

4. Tracking Logs by 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. Tracking Logs by Email

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

📁 Project Structure

src/
├── index.ts              # Main MCP server
├── types/
│   └── index.ts          # TypeScript interfaces and types
└── tools/
    ├── index.ts          # Tool exports
    ├── contacts.ts       # Contact tools
    └── tracking.ts       # Tracking tools

Architecture

• Modular: Each set of tools is in its own file.
• Typed: TypeScript interfaces for all data.
• Scalable: Easy to add new tools.
• Testable: Isolated classes for easy testing.

📋 Example Response

Contact Data

{
  "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"
}

Tracking Logs

{
  "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"
      }
    }
  ]
}

🤝 Contributing

Contributions are very welcome! To contribute:

1. Fork the project.
2. Create a branch for your feature (git checkout -b feature/nova-funcionalidade).
3. Commit your changes (git commit -m 'Add new feature').
4. Push to the branch (git push origin feature/nova-funcionalidade).
5. Open a Pull Request.

Development

# Install dependencies
pnpm install

# Run in development mode
pnpm dev

# Run tests
pnpm test

# Check linting
pnpm lint

# Build for production
pnpm build

📄 License

This project is licensed under the MIT license. See the LICENSE file for more details.

🔗 Useful Links

• ActiveCampaign API Documentation
• Model Context Protocol
• Issues

📞 Support

If you encounter any problems or have questions:

1. Check if there is a similar issue.
2. Create a new issue with details of the problem.
3. Contact through the GitHub issues.