mautic-mcp-bundle

Mautic MCP Bundle

An authenticated Model Context Protocol server embedded in Mautic 7. It exposes structured, permission-aware tools for contacts, segments, campaigns, campaign graphs, emails and A/B tests, analytics, CRM, tags, forms, webhooks, and incremental events.

This is an extended fork of shinde-rahul/plugin-mautic-mcp, originally created by Rahul Shinde. The original project provided the foundation for exposing Mautic through MCP. This fork preserves that attribution and the GPL-3.0-or-later license while expanding the server into a broader Mautic automation interface.

Requirements

• Mautic 7
• PHP 8.2 or newer
• symfony/mcp-bundle 0.6
• HTTPS in production

Installation

Install it directly from GitHub inside your Mautic project:

composer config repositories.mautic-mcp vcs https://github.com/raphaelcangucu/mautic-mcp-bundle
composer require raphaelcangucu/mautic-mcp-bundle:^0.10
php bin/console mautic:plugins:reload
php bin/console cache:clear --env=prod

Alternatively, clone the bundle into plugins/MauticMcpBundle and ensure the root Mautic project has symfony/mcp-bundle:^0.6 installed. Direct installation without the VCS repository declaration will become available after the package is published on Packagist.

The Streamable HTTP endpoint is available at:

https://your-mautic.example/mcp

Each logged-in user can manage their personal bearer token under the Mautic profile page in the MCP Access panel. Tokens inherit that user's Mautic permissions.

Codex configuration

Store the token in an environment variable:

export MAUTIC_MCP_TOKEN='your-personal-token'

Add this to ~/.codex/config.toml:

[mcp_servers.mautic]
url = "https://your-mautic.example/mcp"
bearer_token_env_var = "MAUTIC_MCP_TOKEN"
default_tools_approval_mode = "writes"
tool_timeout_sec = 120
enabled = true

Restart Codex and ask it to run mautic_health.

Capabilities

The server publishes dedicated read and write operations, including evidence-only WhatsApp consent workflows:

• contacts, timelines, deduplication, merge, points, stages, companies, fields, and tags;
• segments and paginated contact-member export through mautic_read_segments with action=members, including phone, mobile, and all configured profile fields;
• campaigns and complete graph editing, including event deletion and lead.changetags actions;
• one-call draft creation for Instagram comment/private-reply campaigns (create_instagram_comment) and approved WhatsApp template campaigns (create_whatsapp_template);
• emails with complete HTML read/write, absolute preview URLs, public-preview and editing-lock controls, safe send preview, test sends, cloning, and A/B variants;
• dedicated mautic_read_email_html retrieval with an explicit HTML output schema for safe read-modify-write workflows;
• reusable email-template creation, HTML editing, preview control, and deletion;
• campaign and email analytics;
• forms and submissions, including safe form/field/submit-action CRUD through mautic_manage_forms;
• webhooks and cursor-based incremental events.
• optional official Meta integration through MauticMetaBundle: connection/asset CRUD, WhatsApp templates, identities, message logs, durable queues, WhatsApp text/template/media/interactive delivery, Instagram replies/DMs and live reads, consent management, and diagnostics.

The Meta tools are mautic_meta_setup, mautic_read_meta, mautic_read_meta_api, mautic_send_meta_message, and mautic_manage_meta. Install and enable raphaelcangucu/mautic-meta-bundle on the same Mautic instance to use them.

Create an Instagram comment campaign with mautic_manage_campaigns using action=create_instagram_comment, confirm=true, and data.instagramComment={assetId,mediaId,keyword,privateReply}. Create a WhatsApp template campaign with action=create_whatsapp_template, confirm=true, and data.whatsapp={assetId,templateName,language,phoneField,bodyParameters,queue,maxAttempts}. Both actions create an unpublished draft; publish it separately after reviewing the returned flow. Use dryRun=true to validate the full definition without writing.

mautic_manage_meta supports upsert_identity to create the first Meta identity or update an existing identity by contactId + assetId + channel. It requires confirm=true and idempotencyKey. The legacy link_identity action only associates an existing identity and therefore requires id to be the Meta Identity ID, not the Mautic contact ID.

Consent tools are register_landing_whatsapp_opt_in, preview_whatsapp_consent_sync, start_whatsapp_consent_sync, get_whatsapp_consent_sync_status, list_whatsapp_consent_sync_rejections, and cancel_whatsapp_consent_sync. Writes require confirm=true and idempotencyKey; preview is strictly read-only and synchronization never sends messages.

For a segment export with authoritative WhatsApp consent, read a member page and pass its contact IDs to mautic_read_meta with resource=identities and contactIds=[...]. Join on contactId; an absent identity means that no Meta consent identity is recorded and must not be interpreted as opt-in.

contactIds is intentionally limited to identity-list reads (resource=identities without id). Omit it when reading messages, queue jobs, templates, assets, or connections. Invalid filters and missing records return a structured MCP result with status=rejected and an error object (field, type, and message) instead of terminating the HTTP transport with a generic 500 response.

Segment membership is independent from Meta consent by default. On action=members, omit metaOptedIn (or pass null) to export every active segment member. Pass true to keep contacts with an active opted-in Meta identity, or false to keep contacts without one, including contacts that have no recorded Meta identity.

Start Meta configuration with:

{"section":"status"}

using mautic_meta_setup. Its sections cover installation, meta_app, connections, assets, webhooks, campaigns, queue, permissions, mcp, and troubleshooting. The result includes current readiness checks, safe UI links, and a callback URL for every configured connection without returning tokens or app secrets. Pass connectionId with section=webhooks to obtain one exact callback URL.

All tools publish MCP annotations and output schemas. Mutations support controls such as dryRun, confirm, idempotencyKey, and optimistic concurrency where applicable.

For form changes, first call mautic_read_forms with action=get and pass its form.dateModified value as expectedDateModified to mautic_manage_forms. Updates are partial: nested fields/actions with an id are updated, those without an id are created, and omitted items are retained. Use data.deleteFieldIds or data.deleteActionIds with confirm=true for explicit removal. Deleting a complete form also requires confirm=true.

Campaign tag action

Create the tag with mautic_manage_tags, then include an action in the campaign graph:

{
  "key": "tag-engaged",
  "name": "Tag engaged contact",
  "type": "lead.changetags",
  "eventType": "action",
  "properties": {
    "add_tags": ["engaged"],
    "remove_tags": []
  }
}

Security

• Use HTTPS and keep bearer tokens out of source control and logs.
• Give users only the Mautic permissions they need.
• Keep write approvals enabled in MCP clients.
• Preview sends and use dryRun before bulk mutations.
• Rotate or revoke a token immediately if it is exposed.

Development checks

From a Mautic installation containing the plugin:

bin/ecs check plugins/MauticMcpBundle
bin/phpstan analyse -c plugins/MauticMcpBundle/phpstan.neon plugins/MauticMcpBundle --no-progress
php bin/console lint:twig plugins/MauticMcpBundle/Resources/views

License

GPL-3.0-or-later. See LICENSE.

Credits

• Rahul Shinde — creator of the original Mautic MCP plugin on which this project is based.
• Raphael Cangucu — maintainer of this extended fork and its campaign-flow, analytics, CRM, tags, email HTML/templates, token-management, and safety-control features.
• Mautic and its contributors — the open-source marketing automation platform integrated by this plugin.
• Model Context Protocol and the Symfony MCP ecosystem — the protocol and server components used by the integration.

Contributions from the upstream project remain governed by their original authorship and Git history. New contributions are credited through commits and pull requests.

Plugin-owned tools (0.17)

Meta and Inbox now supply their own MCP tools. See provider registration, migration and tool contracts. Clear the cache and reconnect MCP clients after updating the coordinated plugins.