Content
# 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
