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:

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

License

ISC