使用说明

Mautic MCP服务器

Mautic 7（Columba Edition）营销自动化平台的综合模型上下文协议（MCP）服务器。使用68个工具同时支持v1（FOSRestBundle）和v2（API平台）端点。

快速开始

# 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

然后将服务器添加到MCP配置中，并开始使用自然语言命令，如：

“在电子邮件中使用gmail搜索所有联系人”
“创建一个新项目来组织我的第一季度活动资源”
“克隆战役5并将其导出以进行暂存”
“将电子邮件模板12发送到其指定的段”

v2.0中的新增功能（Mautic 7支持）

项目（API v2）

使用Mautic7新的API平台v2端点，在单一逻辑结构下组织营销资源。

list_项目, get_工程, 创建项目, update_项目, 补丁工程, 删除项目

活动导入/导出

在环境之间移动完整的活动设置。

clone_campaign -克隆现有活动
出口活动 -导出包含所有相关资产的活动数据
import_campaign -从JSON数据导入活动

活动分析

get_campaign_event_details -活动活动的详细指标
get_campaign_graph_stats -日期范围的活动图统计
get_campaign_map_stats -地理地图统计

基于分段的电子邮件发送

send_email_to_dential -向指定的细分市场发送电子邮件，并实时调整受众

电子邮件回复跟踪

record_email_reply -通过跟踪哈希记录电子邮件回复
get_email_graph_stats -日期范围的电子邮件图表统计

弃用通知

SMS API类已在Mautic 7中删除。这 list_sms 和 create_sms 工具包括弃用警告。

特性

认证

带有自动令牌刷新的OAuth2身份验证
通过环境变量实现安全的凭据管理
API双重支持：v1（FOSRestBundle）和v2（API平台）

联系人管理（6个工具）

create_contact -使用自定义字段创建新联系人
update_contact -更新现有联系信息
get_contact -通过ID或电子邮件检索联系方式
search_contacts -使用筛选器和分页搜索联系人
删除联系人 -从Mautic中删除联系人
add_contact_to-section -将联系人添加到特定细分市场

活动管理（13个工具）

list_campaigns -获取所有活动的状态和统计数据
get_campaign -获取详细的活动信息
create_campaign -创建新活动
add_contact_tocampaign -将联系人添加到活动中
创建自动控制 -创建具有完全事件自动化功能的活动
execute_campaign -手动执行/触发活动
get_campaign_contacts -获取活动中的联系人及其状态
clone_campaign -克隆现有战役（Mautic 7）
出口活动 -导出带有资产的活动数据（Mautic 7）
import_campaign -从JSON数据导入活动（Mautic 7）
get_campaign_event_details -活动事件指标（Mautic 7）
get_campaign_graph_stats -活动图统计（Mautic 7）
get_campaign_map_stats -战役地理统计数据（Mautic 7）

电子邮件操作（8个工具）

send_邮件 -向特定联系人发送电子邮件
list_邮件 -获取所有电子邮件模板和活动
get_email -获取详细的电子邮件信息
create_email_template -创建新的电子邮件模板
get_email_stats -获取电子邮件性能统计数据
send_email_to_dential -向分段发送电子邮件（Mautic 7）
record_email_reply -通过跟踪哈希记录电子邮件回复（Mautic 7）
get_email_graph_stats -电子邮件图表统计（Mautic 7）

表单管理（3个工具）

list_forms -获取所有提交次数的表单
get_form -获取表单详细信息和字段
get_form_submissions -获取表单提交数据

细分管理（3个工具）

list_segments -获取所有联系人细分
create_segment -使用筛选器创建新的联系人段
get_segment_contacts -获取特定细分市场中的联系人

内容管理（7个工具）

list_资产 -获取所有资产（PDF、图像、文档）
获取资产 -按ID获取资产详细信息
创建资产 -创建新资产（本地或远程）
列表_页面 -获取所有登录页面
创建页面 -创建新的登录页面
list_sms -获取所有短信模板[在Mautic 7中已弃用]
create_sms -创建短信模板[在Mautic 7中已弃用]

商业实体（10个工具）

列表_公司 -获取所有公司
创建公司 -创建新公司
add_contact_tocompany -与公司建立联系
create_note -为联系人或公司添加备注
get_contact_notes -获取联系人的所有笔记
list_tags -获取所有可用标签
create_tag -创建新标签
add_contact_tags -为联系人添加标签
列表_类别 -获取所有类别
创建_类别 -创建新类别

高级功能（7个工具）

add_contact_points -为联系人添加点
减法接触点 -从联系人中减去点数
list_stages -获取所有生命周期阶段
change_contact_stage -更改联系人的生命周期阶段
list_contact_fields -获取所有联系人自定义字段
create_contact_field -创建新的联系人自定义字段
get_contact_activity -获取联系人交互历史记录

集成与自动化（5个工具）

list_webhooks -获取所有webhooks
create_webhook -创建新的Webhook
上传文件 -将文件上传到Mautic
list_reports -获取所有报告
创建报告 -创建自定义报告

项目管理-API v2（6个工具，Mautic 7）

list_项目 -列出所有项目
get_工程 -获取项目详细信息
创建项目 -创建新项目
update_项目 -完全更新现有项目
补丁工程 -部分更新项目
删除项目 -删除项目

安装

先决条件

Node.js（v16或更高版本）
npm或纱线
使用API凭据访问Mautic 7实例

设置

克隆存储库：

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

安装依赖项：
```
npm install
```

配置环境变量：

cp .env.example .env

编辑 .env 并填写您的Mautic API证书：

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

构建服务器：
```
npm run build
```

配置MCP设置： 将服务器添加到MCP配置文件中：

{
  "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": []
    }
  }
}

建筑

双重API支持

Mautic 7具有三层API架构：

层	目的	端点
API平台4.x	新的v2 REST端点（JSON-LD/Hydra）	`/api/v2/projects`
FOSRestBundle	现有v1端点	`/api/contacts`, `/api/campaigns`等等。
FOSOAuthServerBundle	OAuth2身份验证	`/oauth/v2/token`

MCP服务器自动管理两个API版本。v1端点使用配置的 MAUTIC_BASE_URL v2端点是自动导出的。

项目结构

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

配置

环境变量

变量	描述	示例
`MAUTIC_BASE_URL`	您的Mautic API基础URL	`https://your-mautic.com/api/`
`MAUTIC_CLIENT_ID`	OAuth2客户端ID	`1_abc123...`
`MAUTIC_CLIENT_SECRET`	OAuth2客户端密码	`secret123...`
`MAUTIC_TOKEN_ENDPOINT`	OAuth2令牌终结点	`https://your-mautic.com/oauth/v2/token`

获取Mautic API证书

以管理员身份登录您的Mautic实例
前往“设置”>“配置”>“API设置”
启用API访问
前往“设置”>“API凭据”
使用OAuth2授权创建新的API凭据
记下客户端ID和客户端密码

错误处理

服务器包括全面的错误处理：

自动刷新OAuth2令牌
来自v1和v2 API格式的详细错误消息
妥善处理身份验证失败
重试瞬态错误的逻辑

安全

所有凭据都存储为环境变量
OAuth2令牌会自动刷新
没有记录或暴露敏感数据
与Mautic API进行安全的HTTPS通信

发展

要修改或扩展服务器，请执行以下操作：

在中编辑源代码 src/ 目录
通过在中创建文件来添加新工具 src/tools/ 并将其导入 src/tools/index.ts
构建服务器： npm run build
使用MCP检查员进行测试： npm run inspector

贡献

我们欢迎捐款！请参阅存储库以获取贡献指南。

许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

致谢

与模型上下文协议SDK v1.26.0
与集成 Mautic 7 （哥伦布版）