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

1. Clone the repository:

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

2. Install dependencies:

   npm install

3. 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

4. Build the server:

   npm run build

5. 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:

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

Obtaining Mautic API Credentials

1. Log into your Mautic instance as an administrator

2. Go to Settings > Configuration > API Settings

3. Enable API access

4. Go to Settings > API Credentials

5. Create a new API credential with OAuth2 authorization

6. 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:

1. Edit the source code in the src/ directory

2. Add new tools by creating a file in src/tools/ and importing it in src/tools/index.ts

3. Build the server: npm run build

4. 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)