Listmonk MCP

Listmonk MCP 服务

这是一个用于 Listmonk 的 MCP 服务。Listmonk 是一款可自托管的新闻简报和邮件列表管理器。它让 AI Agent（Claude Code、Claude Desktop、Cursor、Cline、VS Code 等）能够管理订阅者、邮件列表、营销活动、模板和媒体，并通过你的 Listmonk 实例发送事务性邮件。

这是 Rohan Verma 开发的 rhnvrm/listmonk-mcp 的 TypeScript 移植版，并扩展了基于文件的模板、营销活动正文编辑和强化的文件访问功能。

使用 TypeScript 编写，运行于 Bun。

俄语版

功能

• 订阅者： 添加、更新、删除订阅者，更改状态，使用 Listmonk SQL 查询搜索，并按 ID 或电子邮件查找。
• 邮件列表： 创建、更新、删除和列出邮件列表，以及列出成员。
• 营销活动： 创建、更新、预览、立即发送和安排发送。支持通过纯文本、正则表达式和批量替换编辑正文。
• 模板： 创建、更新、删除和读取模板。大型 HTML 正文（例如 MJML 导出文件）可直接从文件加载。
• 事务性邮件： 向一位收件人发送 tx 模板，并附带自定义数据。
• 媒体： 上传、重命名、删除和列出媒体。

要求

• Bun 1.1 或更高版本。
• Listmonk 和一个 API 用户。在 Listmonk 管理界面中打开 Users，创建一个类型为 API 的用户，并复制其令牌。为其分配仅包含 Agent 所需权限的角色。

快速开始

一键安装（然后在客户端的 MCP 设置中替换占位的 URL、用户名和令牌）：

Claude Code

claude mcp add --transport stdio --scope user \
  --env LISTMONK_MCP_URL=https://listmonk.example.com \
  --env LISTMONK_MCP_USERNAME=api_user \
  --env LISTMONK_MCP_PASSWORD=your-api-token \
  listmonk -- bunx listmonk-mcp-ts

Claude Desktop、Cursor、Cline 和其他客户端

将服务添加到客户端的 MCP 配置（mcpServers 部分）：

{
  "mcpServers": {
    "listmonk": {
      "command": "bunx",
      "args": ["listmonk-mcp-ts"],
      "env": {
        "LISTMONK_MCP_URL": "https://listmonk.example.com",
        "LISTMONK_MCP_USERNAME": "api_user",
        "LISTMONK_MCP_PASSWORD": "your-api-token",
        "LISTMONK_MCP_FILES_DIR": "/path/to/email-templates"
      }
    }
  }
}

各客户端配置文件的位置：Claude Desktop、Cursor 和 Windsurf、Cline、VS Code。

会话打开时，客户端会启动该服务；会话结束时，服务也会停止。你无需让它持续运行。

配置

变量	必填	默认值	说明
LISTMONK_MCP_URL	是		Listmonk 基础 URL，支持 http:// 或 https://
LISTMONK_MCP_USERNAME	是		API 用户名
LISTMONK_MCP_PASSWORD	是		API 用户令牌
LISTMONK_MCP_FILES_DIR	否		文件工具可读取的目录。未设置时，文件工具将被禁用
LISTMONK_MCP_TIMEOUT	否	30	HTTP 超时时间，单位为秒
LISTMONK_MCP_MAX_RETRIES	否	3	网络错误时的重试次数。仅重试 GET 请求
LISTMONK_MCP_SERVER_NAME	否	Listmonk MCP Server	向客户端报告的服务名称

变量也可以来自工作目录中的 .env 文件，或通过 --config /path/to/.env 指定的文件。

CLI 选项：-c, --config <file> 加载环境变量文件，-v, --version 输出版本号。

工具

区域	工具
健康状况	check_listmonk_health
订阅者	add_subscriber、update_subscriber、remove_subscriber、change_subscriber_status、list_subscribers、get_subscriber_by_id、get_subscriber_by_email
邮件列表	get_mailing_lists、get_list_by_id、get_list_subscribers_tool、create_mailing_list、update_mailing_list、delete_mailing_list
Campaign	get_campaigns、get_campaign、get_campaign_preview、create_campaign、update_campaign、send_campaign、schedule_campaign
Campaign 正文	replace_in_campaign_body、regex_replace_in_campaign_body、batch_replace_in_campaign_body
模板	get_templates、get_template、create_template、update_template、create_template_from_file、update_template_from_file、delete_template
事务性邮件	send_transactional_email
媒体	get_media_list、upload_media_file、rename_media、delete_media_file

从文件创建模板

通过工具调用内联传入大型 HTML 正文既耗时，模型在复制时也可能会修改内容。create_template_from_file 和 update_template_from_file 会改为从文件读取正文，因此存储的模板与文件逐字节一致。tx 模板必须提供 subject。

文件路径可以是绝对路径，也可以是相对于 LISTMONK_MCP_FILES_DIR 的路径。

安全

• 文件访问范围仅限 LISTMONK_MCP_FILES_DIR。 create_template_from_file、update_template_from_file 和 upload_media_file 会拒绝访问该目录之外的任何路径（包括符号链接），并且在未设置该目录时会被禁用。从 Listmonk 读取的订阅者姓名、Campaign 正文和其他数据可能包含陌生人写入的指令（提示词注入）。如果没有此限制，这类文本可能会诱使 Agent 读取 ~/.ssh 或 .env 并通过电子邮件发送出去。
• 发送工具应保持审批开启。 send_campaign、schedule_campaign 和 send_transactional_email 会发送真实邮件。请勿在客户端中为它们启用自动审批。
• 使用专用 API 用户，其角色权限应仅限 Agent 所需范围，而非使用管理员账户。
• 不要将令牌放入共享文件。 如果 MCP 配置已提交到版本库或进行同步，请通过环境变量传递令牌。

开发

git clone https://github.com/tecspda/listmonk-mcp-ts.git
cd listmonk-mcp-ts
bun install
cp .env.example .env   # fill in your Listmonk details
bun run start          # run the server
bun run dev            # run with reload on change
bun run check          # type check
bun test               # tests

要从 MCP 客户端运行本地检出版本，请使用 "command": "bun", "args": ["run", "/path/to/listmonk-mcp-ts/src/index.ts"]。

需要 Listmonk 实例进行测试？请参阅 Docker 设置。

许可证

MIT