mcp-mautic

A comprehensive Model Context Protocol (MCP) server for the Mautic 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

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:

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

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

Close and reopen Terminal, then:

nvm install 20
nvm use 20

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

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

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

{
  "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):

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