# mcp-mautic

A comprehensive [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for the [Mautic](https://www.mautic.org/) marketing automation API.

## Features

- **203 tools** covering the full Mautic REST API
- OAuth2 client-credentials authentication with automatic token refresh
- Covers: Contacts, Companies, Segments, Campaigns, Emails, Forms, Pages, Assets, Points, Stages, Tags, Notes, Webhooks, Reports, Stats, Users, Roles, Dynamic Content, Focus Items, SMS, Notifications, and more
- Campaign import/export with ZIP packaging
- CSV contact import
- GDPR-compliant contact erasure and DNC management
- Batch operations for contacts and segments
- Stats API with advanced filtering

## Requirements

- Node.js >= 18
- A Mautic instance with OAuth2 API credentials (client credentials grant)

## Installation

```bash
git clone https://github.com/esanum/mcp-mautic.git
cd mcp-mautic
npm install
```

## Configuration

Set the following environment variables:

| Variable | Description |
|---|---|
| `MAUTIC_BASE_URL` | Your Mautic instance URL (e.g. `https://mautic.example.com`) |
| `MAUTIC_CLIENT_ID` | OAuth2 client ID |
| `MAUTIC_CLIENT_SECRET` | OAuth2 client secret |
| `MAUTIC_TOKEN_URL` | *(optional)* Token endpoint, defaults to `${MAUTIC_BASE_URL}/oauth/v2/token` |

### Setting up OAuth2 in Mautic

1. Go to **Settings > API Credentials** in your Mautic instance
2. Create a new **OAuth 2** credential
3. Set the **Grant Type** to `Client Credentials`
4. Copy the Client ID and Client Secret

## Usage with Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mautic": {
      "command": "node",
      "args": ["/path/to/mcp-mautic/server.js"],
      "env": {
        "MAUTIC_BASE_URL": "https://mautic.example.com",
        "MAUTIC_CLIENT_ID": "your_client_id",
        "MAUTIC_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}
```

## macOS Setup Guide (Step by Step)

This walks you through a clean setup on a Mac, from installing Node.js to seeing the Mautic tools inside Claude Desktop. Replace `yourusername` with your actual macOS user (run `whoami` in Terminal to check).

### 1. Install Node.js via nvm

If you don't have Node 18+ already, the easiest way is nvm:

```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
```

Close and reopen Terminal, then:

```bash
nvm install 20
nvm use 20
```

Find the absolute path to your node binary — you'll need it in the config:

```bash
which node
```

You'll get something like `/Users/yourusername/.nvm/versions/node/v20.18.1/bin/node`. Claude Desktop does not inherit your shell's PATH, so using the absolute path is the most reliable option.

### 2. Clone and install the MCP server

```bash
cd ~
git clone https://github.com/esanum/mcp-mautic.git
cd mcp-mautic
npm install
```

### 3. Locate and edit the Claude Desktop config

The config file lives at:

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

In Finder you can jump there with `Cmd+Shift+G` and pasting the path. If the file doesn't exist yet, create it with the skeleton below.

### 4. Single-instance example

```json
{
  "mcpServers": {
    "mautic": {
      "command": "/Users/yourusername/.nvm/versions/node/v20.18.1/bin/node",
      "args": ["/Users/yourusername/mcp-mautic/server.js"],
      "env": {
        "MAUTIC_BASE_URL": "https://mautic.example.com",
        "MAUTIC_TOKEN_URL": "https://mautic.example.com/oauth/v2/token",
        "MAUTIC_CLIENT_ID": "your_client_id",
        "MAUTIC_CLIENT_SECRET": "your_client_secret",
        "PATH": "/Users/yourusername/.nvm/versions/node/v20.18.1/bin:/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin"
      }
    }
  }
}
```

The `PATH` entry in `env` isn't strictly required when you use an absolute `command` path, but it helps if any child processes (git, etc.) need to be found.

### 5. Multi-instance example

You can connect several Mautic instances in parallel — each one gets its own server entry with its own `MAUTIC_BASE_URL` and credentials. Claude will expose each as a separate toolset (e.g. `mautic`, `mautic-staging`, `mautic-de`):

```json
{
  "mcpServers": {
    "mautic": {
      "command": "/Users/yourusername/.nvm/versions/node/v20.18.1/bin/node",
      "args": ["/Users/yourusername/mcp-mautic/server.js"],
      "env": {
        "MAUTIC_BASE_URL": "https://mautic.example.com",
        "MAUTIC_TOKEN_URL": "https://mautic.example.com/oauth/v2/token",
        "MAUTIC_CLIENT_ID": "your_client_id_prod",
        "MAUTIC_CLIENT_SECRET": "your_client_secret_prod",
        "PATH": "/Users/yourusername/.nvm/versions/node/v20.18.1/bin:/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin"
      }
    },
    "mautic-staging": {
      "command": "/Users/yourusername/.nvm/versions/node/v20.18.1/bin/node",
      "args": ["/Users/yourusername/mcp-mautic/server.js"],
      "env": {
        "MAUTIC_BASE_URL": "https://staging.mautic.example.com",
        "MAUTIC_TOKEN_URL": "https://staging.mautic.example.com/oauth/v2/token",
        "MAUTIC_CLIENT_ID": "your_client_id_staging",
        "MAUTIC_CLIENT_SECRET": "your_client_secret_staging",
        "PATH": "/Users/yourusername/.nvm/versions/node/v20.18.1/bin:/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin"
      }
    }
  }
}
```

Tip: each Mautic instance needs its own OAuth2 credential pair — create one per instance under **Settings → API Credentials** and keep the IDs straight by naming the server entries clearly.

### 6. Restart Claude Desktop

Quit Claude fully (`Cmd+Q` — just closing the window is not enough), then reopen it. Under **Search and tools** the Mautic servers should now appear. Click one to see the list of available Mautic tools.

### 7. Troubleshooting on macOS

Logs live here:

```
~/Library/Logs/Claude/mcp*.log
```

Common issues:

- **Server fails to start / "command not found"** — the `command` path is wrong. Re-run `which node` and paste the exact path.
- **"Cannot find module"** — you forgot `npm install` in the `mcp-mautic` folder, or the `args` path doesn't point to the actual `server.js`.
- **401 from Mautic** — OAuth credentials or `MAUTIC_BASE_URL` wrong; double-check the grant type is `Client Credentials`.
- **JSON parse error on startup** — `claude_desktop_config.json` has a syntax error. Missing comma between server blocks is the usual culprit. Validate with `jsonlint` or any online JSON validator before restarting.
- **Changes don't take effect** — make sure you fully quit Claude Desktop (`Cmd+Q`), not just closed the window.

## Tool Categories

| Category | Tools | Examples |
|---|---|---|
| **Contacts** | 25+ | list, get, create, update, delete, merge, batch ops, GDPR erase |
| **Segments** | 8+ | list, get, create, update, delete, membership, batch add/remove |
| **Campaigns** | 12+ | list, get, create, update, delete, clone, import/export, events |
| **Emails** | 12+ | list, get, create, update, delete, send to contact/segment, stats |
| **Forms** | 10+ | list, get, create, update, delete, submissions, fields, actions |
| **Companies** | 8+ | list, get, create, update, delete, contacts, fields |
| **Pages** | 6+ | list, get, create, update, delete, hit stats |
| **Assets** | 6+ | list, get, create, update, delete, download stats |
| **Points** | 10+ | actions, triggers, groups, add/subtract, change log |
| **Stages** | 6+ | list, get, create, update, add/remove contacts |
| **Tags** | 5 | list, get, create, update, delete |
| **Notes** | 5 | list, get, create, update, delete |
| **Reports** | 3 | list, get report, get report data |
| **Stats** | 3 | list tables, get columns, query stats |
| **Users & Roles** | 8+ | list, get, create, update, delete, permissions |
| **Webhooks** | 6+ | list, get, create, update, delete, triggers, logs |
| **Dynamic Content** | 5+ | list, get, create, update, delete, stats |
| **Focus Items** | 5+ | list, get, create, update, delete, stats |
| **SMS** | 5+ | list, get, create, update, send, stats |
| **Notifications** | 5+ | list, get, create, update, send, stats |
| **Dashboard** | 2 | get data, get data by type |
| **Categories** | 5 | list, get, create, update, delete |
| **Files** | 3 | list, create, delete |
| **Audit Log** | 1 | get audit log entries |

## License

ISC