金大哥 - listmonk-mcp MCP 详情

article

README

🚀 Listmonk MCP 服务器

Listmonk MCP 服务器是一个针对 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 用户和令牌

访问 Listmonk 管理界面：http://localhost:9000/admin
使用默认凭证登录：admin / listmonk
导航到 管理 → 用户（http://localhost:9000/admin/users）
创建一个新的 API 用户：
- 点击“添加新用户”
- 输入用户名（例如：api-user）
- 分配适当的角色/权限
- 保存用户
生成 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

常见错误：“无效会话”或 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 安装实例的交互提供标准化接口。

listmonk-mcp