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:

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

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)