内容
# Mautic MCP 服务器
一款轻量级 [模型上下文协议（MCP）](https://modelcontextprotocol.io) 服务器，连接 **Claude AI** 到您的 **Mautic** 营销自动化平台。一旦连接，您就可以管理联系人、发送电子邮件、运行活动并拉取分析数据 — 所有这些都可以通过 Claude 中的自然语言实现。
由 **[Discret AI](https://ai.discretdigital.com)** 构建和开源。
---
## 功能介绍
```
Claude ↔ MCP 服务器（Node.js）↔ Mautic REST API
```
您可以与 Claude 对话，Claude 将调用您的 Mautic 实例。以下是您可以使用的示例：
> *"获取所有标记为 solar-dealer 的联系人"*
> *"向分段 5 中的所有联系人发送电子邮件 ID 12"*
> *"为 ahmed@example.com 的 Ahmed 创建一个联系人，并将他添加到 solar 活动"*
> *"电子邮件 7 的打开率是多少？"*
> *"向联系人 234 添加标签 follow-up"*
---
## Claude 可用工具
| 工具 | 描述 |
|---|---|
| `get_contacts` | 搜索/列出联系人，可选过滤器 |
| `get_contact` | 通过 ID 获取单个联系人 |
| `create_contact` | 创建具有字段和标签的新联系人 |
| `update_contact` | 更新现有联系人的字段 |
| `delete_contact` | 删除联系人 |
| `send_email` | 向单个联系人发送交易电子邮件 |
| `bulk_send_email` | 向联系人 ID 列表发送电子邮件 |
| `get_email_stats` | 获取电子邮件的打开/点击统计数据 |
| `list_emails` | 列出 Mautic 中的所有电子邮件 |
| `list_segments` | 列出所有联系人分段 |
| `add_contact_to_segment` | 将联系人添加到分段 |
| `remove_contact_from_segment` | 从分段中删除联系人 |
| `list_campaigns` | 列出所有活动 |
| `add_contact_to_campaign` | 将联系人添加到活动 |
| `list_tags` | 列出 Mautic 中定义的所有标签 |
| `add_tag_to_contact` | 向联系人添加一个或多个标签 |
| `get_contact_activity` | 获取联系人的完整事件/活动历史记录 |
| `list_forms` | 列出所有 Mautic 表单 |
| `get_form_submissions` | 获取特定表单的提交记录 |
---
## 先决条件
- [Node.js](https://nodejs.org/) v18 或更高版本
- 运行中的 [Mautic](https://www.mautic.org/) 实例（自托管或云）
- Mautic API 已启用，带有基本身份验证凭据
- [Claude Desktop](https://claude.ai/download) （用于 MCP 集成）
---
## 设置
### 1. 启用 Mautic API
在 Mautic 管理面板中：
1. 进入 **设置 → 配置 → API 设置**
2. 将 **API 已启用** 设置为 `Yes`
3. 将 **启用 HTTP 基本身份验证** 设置为 `Yes`
4. 保存
### 2. 克隆和安装
```bash
git clone https://github.com/abdulhadi-98/mautic-mcp.git
cd mautic-mcp
npm install
```
### 3. 配置凭据
复制示例 env 文件并填写您的详细信息：
```bash
cp .env.example .env
```
编辑 `.env`:
```env
MAUTIC_URL=https://your-mautic-domain.com
MAUTIC_USER=admin
MAUTIC_PASS=yourpassword
```
> **注意：** URL 应为您的 Mautic 根 URL — 不带尾随斜杠。服务器会自动追加 `/api`。
### 4. 连接到 Claude Desktop
打开（或创建）您的 Claude Desktop 配置文件：
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
添加 `mautic` 服务器条目：
```json
{
"mcpServers": {
"mautic": {
"command": "node",
"args": ["/absolute/path/to/mautic-mcp/index.js"]
}
}
}
```
**Windows 示例：**
```json
{
"mcpServers": {
"mautic": {
"command": "node",
"args": ["C:\\Users\\YourName\\mautic-mcp\\index.js"]
}
}
}
```
重启 Claude Desktop。您将在工具栏（锤子图标）中看到 Mautic 工具。
---
## 从 claude.ai（网页）连接
服务器实现 OAuth2，因此它直接在浏览器中的 [claude.ai](https://claude.ai) 上运行 — 不需要桌面应用程序。
### 需要额外的环境变量
将 `SERVER_URL` 添加到您的部署环境（您的服务器的公共 HTTPS URL，不带尾随斜杠）：
```env
SERVER_URL=https://mcp.yourdomain.com
```
### 在 claude.ai 上连接
1. 进入 **claude.ai → 设置 → 集成 → 添加集成**
2. 输入您的服务器 URL：`https://mcp.yourdomain.com`
3. Claude 将重定向到登录页面 — 输入您的 `MCP_API_KEY`
4. 您将被重定向回 Claude，已连接并准备就绪
每个团队成员都经过相同的流程，使用的 API 密钥相同。服务器为每个浏览器会话颁发自己的承载令牌，验证密钥后。
### OAuth 流的工作原理
```
claude.ai → GET /.well-known/oauth-authorization-server （发现）
→ GET /oauth/authorize （登录页面）
→ POST /oauth/authorize （提交 API 密钥） （颁发授权码）
→ POST /oauth/token （交换代码） （颁发承载令牌）
→ POST /mcp （所有工具调用） （需要承载令牌）
```
不需要数据库 — 授权码在 5 分钟内过期，承载令牌存储在内存中。重启服务器使所有令牌失效（用户重新认证一次）。
---
## 使用示例
连接后，在 Claude 中尝试这些提示：
**联系人管理**
```
获取 Mautic 中的前 20 个联系人
搜索电子邮件域名为 @example.com 的联系人
创建联系人：姓名 Ahmed Khan，电子邮件 ahmed@example.com，公司 Solar Co
向联系人 145 添加标签“hot-lead”
```
**发送电子邮件**
```
向联系人 312 发送电子邮件 ID 8
向这些联系人发送电子邮件 ID 8：100、101、102、103、104
电子邮件 12 的打开和点击统计数据是什么？
```
**分段和活动**
```
列出所有分段
将联系人 200 添加到分段 3
列出所有活动并告诉我哪些是活跃的
```
**批量操作**
```
获取所有标记为“solar-dealer”的联系人，并向他们发送电子邮件 ID 5
将下面我粘贴的 10 个联系人添加到分段 7
```
---
## 项目结构
```
mautic-mcp/
├── index.js # MCP 服务器 — 所有工具和 Mautic API 调用
├── package.json # 依赖项
├── .env.example # 凭据模板
└── README.md
```
---
## 身份验证
此服务器使用 **HTTP 基本身份验证** — Mautic 支持的最简单方法。对于生产用例，Mautic 还支持 OAuth2。要切换到 OAuth2，请用 Mautic 的 OAuth2 流中的令牌标头替换 `index.js` 中的 `auth` 配置。
---
## 贡献
欢迎贡献。要添加新工具：
1. 将其架构添加到 `index.js` 中的 `ListToolsRequestSchema` 处理程序
2. 将其执行逻辑添加到 `CallToolRequestSchema` 开关块
3. 打开一个带有工具说明和 Mautic API 端点描述的 PR
请保持工具专注 — 每个工具对应一个 Mautic API 操作。
---
## 许可证
MIT 许可证 — 免费使用、修改和分发。
---
## 致谢
由 **[Discret AI](https://ai.discretdigital.com)** 构建和开源。
> Discret AI 为企业构建 AI 驱动的自动化系统 — 从智能外联管道到自定义 Claude 集成。此 MCP 服务器是我们致力于使 AI + 营销自动化对每个人都可用的承诺的一部分。
---
## 相关资源
- [Mautic REST API 文档](https://developer.mautic.org/#rest-api)
- [模型上下文协议文档](https://modelcontextprotocol.io)
- [Claude Desktop](https://claude.ai/download)
- [Discret AI](https://ai.discretdigital.com)
