Listmonk MCP 服务器

<p align="center"> <img src="https://listmonk.app/static/images/logo.svg" alt="Listmonk Logo" width="150"/> </p>

概述

本项目提供了一个模型上下文协议 (MCP) 服务器，旨在与 Listmonk 实例进行交互。它允许 Cline（或其他 MCP 兼容客户端）的用户直接通过 MCP 接口管理他们的 Listmonk 邮件列表、订阅者、活动等。

该服务器充当桥梁，将 MCP 请求转换为 Listmonk API 调用。

优势

• 将 Listmonk 与 Cline 集成： 在您的 Cline 工作流程中无缝管理 Listmonk 资源和操作。
• 自动化电子邮件营销任务： 编写脚本并自动化常见的 Listmonk 操作，例如添加订阅者、管理列表或检查活动统计信息。
• 集中管理： 与通过 MCP 连接的其他工具和服务一起与 Listmonk 交互。

功能

此服务器公开了与各种 Listmonk API 端点相对应的 MCP 工具：

• 订阅者：

  • get_subscriber(subscriber_id)
  • list_subscribers(query, list_id, status, page, per_page)
  • create_subscriber(email, name, status, lists, attribs, preconfirm)
  • update_subscriber(subscriber_id, email, name, status, lists, attribs)
  • delete_subscriber(subscriber_id)
  • blocklist_subscriber(subscriber_id)
  • manage_subscriber_lists(subscriber_ids, action, list_ids, status)

• 列表：

  • get_list(list_id)
  • list_lists(query, status, tag, page, per_page)
  • create_list(name, type, optin, tags, description)
  • update_list(list_id, name, type, optin, tags, description)
  • delete_list(list_id)

• 活动：

  • get_campaign(campaign_id, no_body=False): 检索活动详细信息（包括基本统计信息，如浏览量、点击量、发送计数）。
  • list_campaigns(query=None, status=None, tags=None, page=1, per_page=100, no_body=False)
  • create_campaign(name, subject, lists, type, content_type, body, from_email=None, altbody=None, send_at=None, messenger=None, template_id=None, tags=None, headers=None)
  • update_campaign(campaign_id, name=None, subject=None, lists=None, ...): 更新活动的指定字段。
  • delete_campaign(campaign_id)
  • change_campaign_status(campaign_id, status)

• 模板：

  • list_templates()
  • get_template(template_id)
  • preview_template(template_id)
  • create_template(name, type, body, subject=None)
  • update_template(template_id, name=None, type=None, body=None, subject=None)
  • set_default_template(template_id)
  • delete_template(template_id)
  • render_template_preview(body, type, subject=None)

• 退回邮件：

  • list_bounces(campaign_id=None, page=None, per_page=None, source=None, order_by=None, order=None)
  • delete_bounces(ids=None, all=None)
  • delete_bounce(bounce_id)

• 事务性：

  • send_transactional_message(template_id, subscriber_email=None, subscriber_id=None, subscriber_emails=None, subscriber_ids=None, from_email=None, data=None, headers=None, messenger=None, content_type=None): 使用事务性模板发送消息。

设置和配置

1. 先决条件：

   • 一个正在运行的 Listmonk 实例。
   • 已安装 Python 3.x。

2. 安装：

   • 克隆此存储库（或获取打包的服务器）。
   • 导航到服务器目录。
   • 设置 Python 虚拟环境：

     python3 -m venv venv
     source venv/bin/activate  # Linux/macOS
     # or .\venv\Scripts\activate # Windows
     

   • 安装依赖项：

     pip install -r requirements.txt
     

3. 环境变量： 在项目根目录中创建一个 .env 文件（或直接设置环境变量）。复制 .env.example 的内容并填写您的 Listmonk API 详细信息：

   # .env
   LISTMONK_API_ENDPOINT="https://your-listmonk-instance.com/api"
   LISTMONK_API_USER="your_api_username"
   LISTMONK_API_TOKEN="your_api_password_or_token"
   

   服务器使用 python-dotenv 库来加载这些变量。

4. 配置（MCP 设置）： 将此服务器添加到 MCP 客户端的配置（例如，cline_mcp_settings.json）时，通常只需要指定运行服务器的命令。服务器将从 .env 文件或系统环境中获取凭据。

   • LISTMONK_API_ENDPOINT: Listmonk API 的完整 URL（例如，https://your-listmonk.com/api）。
   • LISTMONK_API_USER: 在 Listmonk 中创建的 API 访问用户名（管理 -> 用户 -> API）。
   • LISTMONK_API_TOKEN: 用户的相应 API 访问令牌。

   cline_mcp_settings.json 示例条目：

   {
     "mcpServers": {
       "listmonk": {
         "command": "python",
         "args": ["/path/to/listmonk-mcp/src/main.py"],
         "env": {
           "LISTMONK_API_ENDPOINT": "YOUR_LISTMONK_API_URL",
           "LISTMONK_API_USER": "YOUR_API_USERNAME",
           "LISTMONK_API_TOKEN": "YOUR_API_TOKEN"
         },
         "disabled": false,
         "autoApprove": []
       }
     }
   }
   

   (注意：command 和 args 可能会因打包方式而异。)

用法/教程（MCP 工具调用示例）

服务器实现和配置完成后，您可以使用如下工具（语法可能因 MCP 客户端而异）：

列出订阅者：

{
  "tool_name": "list_subscribers",
  "arguments": {
    "per_page": 10
  }
}

创建订阅者：

{
  "tool_name": "create_subscriber",
  "arguments": {
    "email": "new.subscriber@example.com",
    "name": "New Subscriber",
    "status": "enabled",
    "lists": [3, 4],
    "preconfirm": true
  }
}

获取活动详细信息：

{
  "tool_name": "get_campaign",
  "arguments": {
    "campaign_id": 5
  }
}

开发

此服务器使用 Python 构建。主要依赖项包括：

• requests: 用于向 Listmonk API 发出 HTTP 调用。
• python-dotenv: 用于从 .env 文件加载环境变量。

代码结构按资源类型组织工具处理程序：

• src/main.py: 主服务器入口点，加载配置并处理 MCP 请求路由。
• src/client.py: 用于发出经过身份验证的 API 请求的集中式助手。
• src/subscribers.py: 用于订阅者相关工具的逻辑。
• src/lists.py: 用于列表相关工具的逻辑。
• src/campaigns.py: 用于活动相关工具的逻辑。
• src/templates.py: 用于模板相关工具的逻辑。
• src/bounces.py: 用于退回邮件相关工具的逻辑。
• src/transactional.py: 用于事务性消息工具的逻辑。