npm package: @marcelocorrea/mcp-active-campaign
Description: MCP server for ActiveCampaign API v3 with 13 resource-based tools
Latest version: 1.0.3

# ActiveCampaign MCP Server

MCP (Model Context Protocol) server for ActiveCampaign API v3, providing 13 resource-based tools for comprehensive API access.

## Features

- **13 Resource-Based Tools**: Organized by domain (accounts, contacts, deals, etc.)
- **Dynamic Endpoint Construction**: Each tool supports multiple operations
- **Comprehensive Coverage**: Access to 141+ ActiveCampaign API endpoints
- **Type-Safe**: Full TypeScript-compatible schemas

## Resource Tools

1. **accounts** - Manage accounts (list, get, create, update, delete, bulk operations)
2. **contacts** - Manage contacts and related data (lists, tags, automations, deals, etc.)
3. **campaigns** - Access campaign data
4. **messages** - Retrieve messages
5. **tags** - Manage tags and contact associations
6. **lists** - Manage lists and contact subscriptions
7. **custom_objects** - Work with custom object schemas and records
8. **groups** - Manage field groups
9. **users** - Manage users
10. **deals** - Manage deals, pipelines, and stages
11. **tracking** - Site and event tracking operations
12. **ecommerce** - E-commerce orders, customers, and products
13. **webhooks** - Configure webhooks and events

## Installation

```bash
npm run build
```

Or:

```bash
npm install
```

## Configuration

### Option 1: Using .env file (Recommended)

1. Copy the example file:
```bash
cp .env.example .env
```

2. Edit `.env` and add your credentials:
```env
ACTIVECAMPAIGN_API_KEY=your-api-key
ACTIVECAMPAIGN_ACCOUNT_URL=https://youraccountname.api-us1.com
```

### Option 2: Using environment variables

```bash
export ACTIVECAMPAIGN_API_KEY="your-api-key"
export ACTIVECAMPAIGN_ACCOUNT_URL="https://youraccountname.api-us1.com"
```

## Usage

### Running the Server

```bash
npm start
```

### Claude Desktop Configuration

Add to your Claude Desktop config file:

**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "activecampaign": {
      "command": "node",
      "args": ["/path/to/mcp-active-campaign/index.js"],
      "env": {
        "ACTIVECAMPAIGN_API_KEY": "your-api-key",
        "ACTIVECAMPAIGN_ACCOUNT_URL": "https://youraccountname.api-us1.com"
      }
    }
  }
}
```

## Tool Usage Examples

### Contacts Tool

```javascript
// List contacts with filters
{
  "operation": "list",
  "params": {
    "limit": 20,
    "filters[email]": "user@example.com"
  }
}

// Get a specific contact
{
  "operation": "get",
  "id": "123"
}

// Create a new contact
{
  "operation": "create",
  "data": {
    "contact": {
      "email": "newuser@example.com",
      "firstName": "John",
      "lastName": "Doe"
    }
  }
}

// Get contact tags
{
  "operation": "get_tags",
  "id": "123"
}

// Get contact automations
{
  "operation": "get_automations",
  "id": "123"
}
```

### Deals Tool

```javascript
// List all deals
{
  "operation": "list",
  "params": {
    "limit": 50
  }
}

// Create a deal
{
  "operation": "create",
  "data": {
    "deal": {
      "title": "New Deal",
      "value": 5000,
      "currency": "usd",
      "contact": "123",
      "stage": "1"
    }
  }
}

// List pipeline stages
{
  "operation": "list_stages"
}
```

### Tags Tool

```javascript
// List all tags
{
  "operation": "list"
}

// Create a tag
{
  "operation": "create",
  "data": {
    "tag": {
      "tag": "VIP Customer",
      "tagType": "contact"
    }
  }
}

// Add tag to contact
{
  "operation": "add_to_contact",
  "contact_id": "123",
  "data": {
    "contactTag": {
      "contact": "123",
      "tag": "456"
    }
  }
}
```

### Accounts Tool

```javascript
// List accounts
{
  "operation": "list",
  "params": {
    "limit": 100
  }
}

// Bulk delete accounts
{
  "operation": "bulk_delete",
  "ids": ["123", "456", "789"]
}
```

### E-commerce Tool

```javascript
// List orders
{
  "operation": "list_orders",
  "params": {
    "limit": 50
  }
}

// Create customer
{
  "operation": "create_customer",
  "data": {
    "ecomCustomer": {
      "connectionid": "1",
      "externalid": "customer123",
      "email": "customer@example.com"
    }
  }
}

// Sync order
{
  "operation": "sync_order",
  "data": {
    "ecomOrder": {
      "externalid": "order123",
      "email": "customer@example.com",
      "totalPrice": 10000,
      "currency": "USD"
    }
  }
}
```

### Webhooks Tool

```javascript
// List webhooks
{
  "operation": "list"
}

// Create webhook
{
  "operation": "create",
  "data": {
    "webhook": {
      "name": "Contact Created",
      "url": "https://yoursite.com/webhook",
      "events": ["subscribe"],
      "sources": ["public", "admin"]
    }
  }
}

// List available events
{
  "operation": "list_events"
}
```

## Available Operations by Tool

### accounts
- `list`, `get`, `create`, `update`, `delete`, `bulk_delete`, `create_note`, `update_note`

### contacts
- `list`, `get`, `create`, `update`, `delete`, `sync`
- `get_data`, `get_tags`, `get_automations`, `get_lists`, `get_deals`
- `get_field_values`, `get_bounce_logs`, `get_geo_ips`, `get_notes`

### campaigns
- `list`, `get`, `get_links`

### messages
- `list`, `get`

### tags
- `list`, `get`, `create`, `update`, `delete`
- `add_to_contact`, `remove_from_contact`

### lists
- `list`, `get`, `create`, `update`, `delete`
- `add_contact`, `remove_contact`, `update_contact_status`

### custom_objects
- `list_schemas`, `get_schema`, `create_schema`, `update_schema`, `delete_schema`
- `list_records`, `get_record`, `create_record`, `update_record`, `delete_record`

### groups
- `list`, `get`, `create`, `update`, `delete`

### users
- `list`, `get`, `create`, `update`, `delete`

### deals
- `list`, `get`, `create`, `update`, `delete`
- `create_note`, `update_note`
- `get_pipeline`, `list_stages`, `create_stage`, `update_stage`, `delete_stage`

### tracking
- `track_event`, `list_site_tracking`, `get_site_tracking`
- `enable_site_tracking`, `disable_site_tracking`, `whitelist_domain`

### ecommerce
- `list_orders`, `get_order`, `create_order`, `update_order`, `delete_order`
- `list_customers`, `get_customer`, `create_customer`, `update_customer`, `delete_customer`
- `list_products`, `create_product`, `sync_order`, `create_connection`

### webhooks
- `list`, `get`, `create`, `update`, `delete`, `list_events`

## Common Parameters

All tools support these common parameters:

- **operation** (required): The operation to perform
- **id**: Resource ID for get/update/delete operations
- **data**: Request body for create/update operations
- **params**: Query parameters (filters, limit, offset, include, etc.)

## Error Handling

The server provides detailed error messages:
- Missing required parameters
- Invalid operation names
- API errors with status codes

## Development

```bash
# Watch mode for development
npm run dev
```

## API Documentation

For detailed API documentation, visit:
https://developers.activecampaign.com/reference/overview

## License

MIT