Listmonk MCP

🚀 Listmonk MCP Server

Listmonk MCP Server 是一个为 Listmonk 实现的 MCP（模型上下文协议）服务器，它提供了以编程方式访问新闻通讯和邮件列表管理功能的途径。

🚀 快速开始

1. 搭建 Listmonk（本地开发）

为了进行测试，你可以使用 Docker 运行一个本地的 Listmonk 实例：

# 选项 1：使用提供的 compose 文件
docker compose -f docs/listmonk-docker-compose.yml up -d

# 选项 2：下载最新的 compose 文件
curl -LO https://github.com/knadh/listmonk/raw/master/docker-compose.yml
docker compose up -d

# 通过 http://localhost:9000 访问 Listmonk
# 默认凭证：admin / listmonk

2. 创建 API 用户和令牌

1. 访问 Listmonk 管理界面：http://localhost:9000/admin
2. 使用默认凭证登录：admin / listmonk
3. 导航至 管理 → 用户（http://localhost:9000/admin/users）
4. 创建一个新的 API 用户：
   • 点击“添加新用户”
   • 输入用户名（例如，api-user）
   • 分配适当的角色/权限
   • 保存用户
5. 生成 API 令牌：
   • 点击已创建的用户
   • 点击“生成 API 令牌”
   • 复制生成的令牌

3. 配置环境变量

MCP 服务器需要以下环境变量：

export LISTMONK_MCP_URL=http://localhost:9000
export LISTMONK_MCP_USERNAME=your-api-username
export LISTMONK_MCP_PASSWORD=your-generated-api-token

⚠️ 重要提示

密码字段应包含 API 令牌（而非用户的登录密码）。服务器使用 Listmonk 的令牌认证格式：Authorization: token username:api_token。

💡 使用建议

• 验证变量：echo $LISTMONK_MCP_URL 应显示你的 Listmonk URL
• 测试 API 访问：curl -H "Authorization: token username:api_token" http://localhost:9000/api/health
• 常见错误：“invalid session” 或 403 错误表示凭证不正确

4. 运行 MCP 服务器

# 使用 uv（推荐）
uv run python -m listmonk_mcp.server

# 或者使用入口点
listmonk-mcp

⚠️ 重要提示

• 连接被拒绝：Listmonk 服务器未运行或 URL 错误
• 未找到模块：使用 uv install 或 pip install -e . 安装依赖项

✨ 主要特性

• 完整覆盖 Listmonk API：支持所有主要的 Listmonk 操作
• 18 个 MCP 工具：全面的订阅者、列表、活动和模板管理
• MCP 资源：轻松访问订阅者、列表、活动和模板数据
• 异步操作：采用现代的异步/等待模式构建
• 类型安全：完整的 Pydantic 模型验证
• 环境配置：通过环境变量轻松设置

📦 安装指南

使用 uv（推荐）

git clone https://github.com/rhnvrm/listmonk-mcp.git
cd listmonk-mcp

使用 pip

git clone https://github.com/rhnvrm/listmonk-mcp.git
cd listmonk-mcp
pip install -e .

📚 详细文档

项目状态

✅ 实现完成 - 核心 MCP 服务器已完全实现并可正常使用。

目标

创建一个 MCP 服务器，使大语言模型（LLMs）和 AI 助手能够通过模型上下文协议与 Listmonk 实例进行交互。这将实现以下功能：

• 订阅者管理（添加、删除、更新订阅者）
• 邮件列表操作（创建、管理列表）
• 活动管理（创建、发送新闻通讯）
• 分析和报告访问
• 模板和内容管理

架构

该服务器将 MCP 协议与 Listmonk 的 REST API 进行桥接，为 AI 模型与 Listmonk 安装实例的交互提供标准化接口。