Mautic MCP Server

A comprehensive Model Context Protocol (MCP) server for Mautic 7 (Columba Edition) marketing automation platform. Supports both v1 (FOSRestBundle) and v2 (API Platform) endpoints with 68 tools.

Quick Start

# Clone and setup
git clone https://github.com/Cbrown35/mantic-MCP.git
cd mantic-MCP
npm install

# Configure your Mautic credentials
cp .env.example .env
# Edit .env with your Mautic API credentials

# Build and run
npm run build

Then add the server to your MCP configuration and start using natural language commands like:

"Search for all contacts with gmail in their email"
"Create a new project to organize my Q1 campaign resources"
"Clone campaign 5 and export it for staging"
"Send email template 12 to its assigned segment"

What's New in v2.0 (Mautic 7 Support)

Projects (API v2)

Organize marketing resources under a single logical structure using Mautic 7's new API Platform v2 endpoints.

list_projects, get_project, create_project, update_project, patch_project, delete_project

Campaign Import/Export

Move complete campaign setups between environments.

clone_campaign - Clone an existing campaign
export_campaign - Export campaign data with all related assets
import_campaign - Import a campaign from JSON data

Campaign Analytics

get_campaign_event_details - Detailed metrics for campaign events
get_campaign_graph_stats - Campaign graph statistics for date ranges
get_campaign_map_stats - Geographic map statistics

Segment-Based Email Sending

send_email_to_segment - Send email to assigned segments with real-time audience adaptation

Email Reply Tracking

record_email_reply - Record email replies by tracking hash
get_email_graph_stats - Email graph statistics for date ranges

Deprecation Notice

SMS API classes have been removed in Mautic 7. The list_sms and create_sms tools include deprecation warnings.

Features

Authentication

OAuth2 authentication with automatic token refresh
Secure credential management through environment variables
Dual API support: v1 (FOSRestBundle) and v2 (API Platform)

Contact Management (6 tools)

create_contact - Create new contacts with custom fields
update_contact - Update existing contact information
get_contact - Retrieve contact details by ID or email
search_contacts - Search contacts with filters and pagination
delete_contact - Remove contacts from Mautic
add_contact_to_segment - Add contacts to specific segments

Campaign Management (13 tools)

list_campaigns - Get all campaigns with status and statistics
get_campaign - Get detailed campaign information
create_campaign - Create new campaigns
add_contact_to_campaign - Add contacts to campaigns
create_campaign_with_automation - Create campaigns with full event automation
execute_campaign - Manually execute/trigger campaigns
get_campaign_contacts - Get contacts in a campaign with their status
clone_campaign - Clone an existing campaign (Mautic 7)
export_campaign - Export campaign data with assets (Mautic 7)
import_campaign - Import campaign from JSON data (Mautic 7)
get_campaign_event_details - Campaign event metrics (Mautic 7)
get_campaign_graph_stats - Campaign graph statistics (Mautic 7)
get_campaign_map_stats - Campaign geographic stats (Mautic 7)

Email Operations (8 tools)

send_email - Send emails to specific contacts
list_emails - Get all email templates and campaigns
get_email - Get detailed email information
create_email_template - Create new email templates
get_email_stats - Get email performance statistics
send_email_to_segment - Send email to segments (Mautic 7)
record_email_reply - Record email reply by tracking hash (Mautic 7)
get_email_graph_stats - Email graph statistics (Mautic 7)

Form Management (3 tools)

list_forms - Get all forms with submission counts
get_form - Get form details and fields
get_form_submissions - Get form submission data

Segment Management (3 tools)

list_segments - Get all contact segments
create_segment - Create new contact segments with filters
get_segment_contacts - Get contacts in a specific segment

Content Management (7 tools)

list_assets - Get all assets (PDFs, images, documents)
get_asset - Get asset details by ID
create_asset - Create new assets (local or remote)
list_pages - Get all landing pages
create_page - Create new landing pages
list_sms - Get all SMS templates [DEPRECATED in Mautic 7]
create_sms - Create SMS templates [DEPRECATED in Mautic 7]

Business Entities (10 tools)

list_companies - Get all companies
create_company - Create new companies
add_contact_to_company - Associate contacts with companies
create_note - Add notes to contacts or companies
get_contact_notes - Get all notes for a contact
list_tags - Get all available tags
create_tag - Create new tags
add_contact_tags - Add tags to contacts
list_categories - Get all categories
create_category - Create new categories

Advanced Features (7 tools)

add_contact_points - Add points to contacts
subtract_contact_points - Subtract points from contacts
list_stages - Get all lifecycle stages
change_contact_stage - Change contact's lifecycle stage
list_contact_fields - Get all contact custom fields
create_contact_field - Create new contact custom fields
get_contact_activity - Get contact interaction history

Integration & Automation (5 tools)

list_webhooks - Get all webhooks
create_webhook - Create new webhooks
upload_file - Upload files to Mautic
list_reports - Get all reports
create_report - Create custom reports

Project Management - API v2 (6 tools, Mautic 7)

list_projects - List all projects
get_project - Get project details
create_project - Create a new project
update_project - Fully update an existing project
patch_project - Partially update a project
delete_project - Delete a project

Installation

Prerequisites

Node.js (v16 or higher)
npm or yarn
Access to a Mautic 7 instance with API credentials

Setup

Clone the repository:

git clone https://github.com/Cbrown35/mantic-MCP.git
cd mantic-MCP

Install dependencies:
```
npm install
```

Configure environment variables:

cp .env.example .env

Edit .env and fill in your Mautic API credentials:

MAUTIC_BASE_URL=https://your-mautic-instance.com/api/
MAUTIC_CLIENT_ID=your_client_id_here
MAUTIC_CLIENT_SECRET=your_client_secret_here
MAUTIC_TOKEN_ENDPOINT=https://your-mautic-instance.com/oauth/v2/token

Build the server:
```
npm run build
```

Configure MCP settings: Add the server to your MCP configuration file:

{
  "mcpServers": {
    "mautic-server": {
      "command": "node",
      "args": ["/path/to/mautic-server/build/index.js"],
      "env": {
        "MAUTIC_BASE_URL": "https://your-mautic-instance.com/api/",
        "MAUTIC_CLIENT_ID": "your_client_id",
        "MAUTIC_CLIENT_SECRET": "your_client_secret",
        "MAUTIC_TOKEN_ENDPOINT": "https://your-mautic-instance.com/oauth/v2/token"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Architecture

Dual API Support

Mautic 7 has a three-tier API architecture:

Layer	Purpose	Endpoints
API Platform 4.x	New v2 REST endpoints (JSON-LD/Hydra)	`/api/v2/projects`
FOSRestBundle	Existing v1 endpoints	`/api/contacts`, `/api/campaigns`, etc.
FOSOAuthServerBundle	OAuth2 authentication	`/oauth/v2/token`

The MCP server automatically manages both API versions. v1 endpoints use the configured MAUTIC_BASE_URL directly, while v2 endpoints are derived automatically.

Project Structure

src/
├── index.ts              # Entry point: server setup and startup
├── types/                # TypeScript interfaces
│   ├── common.ts         # Shared types (OAuth2Token, ToolResult, etc.)
│   ├── contacts.ts       # MauticContact interface
│   ├── campaigns.ts      # MauticCampaign interface
│   ├── emails.ts         # MauticEmail interface
│   ├── forms.ts          # MauticForm interface
│   ├── segments.ts       # MauticSegment interface
│   └── projects.ts       # MauticProject interface (Mautic 7)
├── api/
│   └── client.ts         # Dual API client (v1 + v2) with OAuth2
└── tools/
    ├── index.ts           # Tool registry and dispatch
    ├── contacts.ts        # Contact tools
    ├── campaigns.ts       # Campaign tools (includes Mautic 7 additions)
    ├── emails.ts          # Email tools (includes Mautic 7 additions)
    ├── forms.ts           # Form tools
    ├── segments.ts        # Segment tools
    ├── projects.ts        # Project tools (Mautic 7 API v2)
    ├── content.ts         # Asset, page, and SMS tools
    ├── business.ts        # Company, note, tag, and category tools
    ├── advanced.ts        # Points, stages, fields, and activity tools
    └── integration.ts     # Webhook, file, and report tools

Configuration

Environment Variables

Variable	Description	Example
`MAUTIC_BASE_URL`	Your Mautic API base URL	`https://your-mautic.com/api/`
`MAUTIC_CLIENT_ID`	OAuth2 Client ID	`1_abc123...`
`MAUTIC_CLIENT_SECRET`	OAuth2 Client Secret	`secret123...`
`MAUTIC_TOKEN_ENDPOINT`	OAuth2 Token Endpoint	`https://your-mautic.com/oauth/v2/token`

Obtaining Mautic API Credentials

Log into your Mautic instance as an administrator
Go to Settings > Configuration > API Settings
Enable API access
Go to Settings > API Credentials
Create a new API credential with OAuth2 authorization
Note down the Client ID and Client Secret

Error Handling

The server includes comprehensive error handling:

Automatic OAuth2 token refresh
Detailed error messages from both v1 and v2 API formats
Graceful handling of authentication failures
Retry logic for transient errors

Security

All credentials are stored as environment variables
OAuth2 tokens are automatically refreshed
No sensitive data is logged or exposed
Secure HTTPS communication with Mautic API

Development

To modify or extend the server:

Edit the source code in the src/ directory
Add new tools by creating a file in src/tools/ and importing it in src/tools/index.ts
Build the server: npm run build
Test with the MCP Inspector: npm run inspector

Contributing

We welcome contributions! Please see the repository for contribution guidelines.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Built with the Model Context Protocol SDK v1.26.0
Integrates with Mautic 7 (Columba Edition)

Mautic