@kieksme/listmonk-mcp

一个 MCP（模型上下文协议）服务器，将完整的 Listmonk REST API（14 个类别共 72 个工具）暴露给兼容 MCP 的 LLM 客户端——既可以作为本地 stdio 进程由你的客户端自行启动，也可以作为远程 Streamable HTTP 部署，供任意数量的客户端连接。

基于 Listmonk OpenAPI 规范 构建。

快速开始

本地： 让你的 MCP 客户端通过 stdio 自行启动服务器——无需手动运行任何命令，也无需开放端口。将其添加到客户端的配置中（此处以 Claude Code 为例；Cursor、VS Code、Claude Desktop、OpenCode、LM Studio 和 ChatGPT 请参阅下文连接你的 MCP 客户端）：

claude mcp add listmonk \
  -e LISTMONK_URL=https://newsletter.example.com \
  -e LISTMONK_API_USER=my-api-user \
  -e LISTMONK_API_TOKEN=xxxxxxxx \
  -- npx -y @kieksme/listmonk-mcp --stdio

远程： 启动一次服务器，即可通过 HTTP 供任意数量的客户端访问：

LISTMONK_URL=https://newsletter.example.com \
LISTMONK_API_USER=my-api-user \
LISTMONK_API_TOKEN=xxxxxxxx \
npx @kieksme/listmonk-mcp

claude mcp add --transport http listmonk http://localhost:3000/mcp

有关两种模式的更多详细信息（包括 Docker），请参阅运行服务器。

Related MCP server: listmonk-mcp-bridge

连接你的 MCP 客户端

下面的每个客户端都支持两种配置——任选其一：

• 本地（stdio）： 客户端自行将 npx @kieksme/listmonk-mcp --stdio 作为子进程启动，并通过其 stdin/stdout 进行 MCP 通信。无需保持服务器运行、无需端口、无需担心可达性——对于单个本地客户端来说，这通常是更简单的默认选择。

• 远程（HTTP）： 你自己运行服务器（参见运行服务器），客户端连接到其 URL。当多个客户端共享一个服务器实例，或服务器运行在非本机的其他位置时，需要这种配置。

在本地/stdio 配置中使用 pnpm 替代 npx： 下面每个本地（stdio）示例都使用 command: "npx" 和 args: ["-y", "@kieksme/listmonk-mcp", "--stdio"]。如果你更倾向于 pnpm，可以换成 command: "pnpm" 和 args: ["dlx", "@kieksme/listmonk-mcp", "--stdio"]——并且去掉 -y。-y 是 npx 的“跳过安装确认提示”标志；pnpm dlx 本来就没有这种提示，所以它完全不接受 -y，会立即以 ERROR Unknown option: 'y' 退出（由于进程在开始 MCP 通信之前就死掉了，客户端只会看到一条泛泛的“Connection closed”）。下面任何以 npx -y 开头的 CLI 形式都适用同样的替换——将其替换为 pnpm dlx（不带 -y）。

远程/HTTP 配置的可达性说明： 只有当客户端与服务器运行在同一台机器上时，才需要使用 http://localhost:3000。Claude Code、Cursor、VS Code、OpenCode 和 LM Studio 都是本地工具，因此 localhost 可以直接使用。Claude Desktop 是本地应用，通常也能访问 localhost。ChatGPT 和 Claude.ai（Web 应用）运行在云端，无法访问你的 localhost——要将此服务器与它们配合使用，你需要将其部署到互联网可访问的位置（或通过隧道，例如 ngrok http 3000），并使用该公共 URL。ChatGPT 的连接器仅支持 HTTP，因此下面没有本地/stdio 选项。

Claude Code

本地（stdio），通过仓库根目录下的 .mcp.json 进行项目级配置：

{
  "mcpServers": {
    "listmonk": {
      "command": "npx",
      "args": ["-y", "@kieksme/listmonk-mcp", "--stdio"],
      "env": {
        "LISTMONK_URL": "https://newsletter.example.com",
        "LISTMONK_API_USER": "my-api-user",
        "LISTMONK_API_TOKEN": "xxxxxxxx"
      }
    }
  }
}

或者通过 CLI：

claude mcp add listmonk \
  -e LISTMONK_URL=https://newsletter.example.com \
  -e LISTMONK_API_USER=my-api-user \
  -e LISTMONK_API_TOKEN=xxxxxxxx \
  -- npx -y @kieksme/listmonk-mcp --stdio

远程（HTTP），在服务器运行后（参见运行服务器）：

{
  "mcpServers": {
    "listmonk": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

claude mcp add --transport http listmonk http://localhost:3000/mcp

如果你在服务器上设置了 MCP_SERVER_AUTH_TOKEN，请添加请求头：claude mcp add --transport http listmonk http://localhost:3000/mcp --header "Authorization: Bearer <token>"。

Cursor

一键安装（本地/stdio，其中包含占位凭据，之后你需要在 Cursor 的 MCP 设置中填写）：

或者手动配置——本地（stdio），通过仓库根目录下的 .cursor/mcp.json（或全局的 ~/.cursor/mcp.json）：

{
  "mcpServers": {
    "listmonk": {
      "command": "npx",
      "args": ["-y", "@kieksme/listmonk-mcp", "--stdio"],
      "env": {
        "LISTMONK_URL": "https://newsletter.example.com",
        "LISTMONK_API_USER": "my-api-user",
        "LISTMONK_API_TOKEN": "xxxxxxxx"
      }
    }
  }
}

远程（HTTP），在服务器运行后：

{
  "mcpServers": {
    "listmonk": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

如果你在服务器上设置了 MCP_SERVER_AUTH_TOKEN，请将其作为请求头传递：

{
  "mcpServers": {
    "listmonk": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

你也可以通过 Cursor 设置 → MCP → 添加新的 MCP 服务器 添加任一配置。

VS Code

一键安装（本地/stdio，其中包含占位凭据，之后你需要在 VS Code 的 MCP 设置中填写）：

或者手动配置——本地（stdio），通过仓库根目录下的 .vscode/mcp.json：

{
  "servers": {
    "listmonk": {
      "command": "npx",
      "args": ["-y", "@kieksme/listmonk-mcp", "--stdio"],
      "env": {
        "LISTMONK_URL": "https://newsletter.example.com",
        "LISTMONK_API_USER": "my-api-user",
        "LISTMONK_API_TOKEN": "xxxxxxxx"
      }
    }
  }
}

远程（HTTP），在服务器运行后（这里需要 type，因为没有 command 可以推断）：

{
  "servers": {
    "listmonk": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Claude Desktop

本地（stdio），在 claude_desktop_config.json 中：

{
  "mcpServers": {
    "listmonk": {
      "command": "npx",
      "args": ["-y", "@kieksme/listmonk-mcp", "--stdio"],
      "env": {
        "LISTMONK_URL": "https://newsletter.example.com",
        "LISTMONK_API_USER": "my-api-user",
        "LISTMONK_API_TOKEN": "xxxxxxxx"
      }
    }
  }
}

远程（HTTP）：设置 → 连接器 → 添加自定义连接器，然后将 http://localhost:3000/mcp 粘贴为 URL（服务器必须已在运行）。如果你的 Claude Desktop 版本的配置文件直接支持远程服务器，等效的配置项是：

{
  "mcpServers": {
    "listmonk": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

OpenCode

本地（stdio），在 opencode.json（项目或全局配置）中：

{
  "mcp": {
    "listmonk": {
      "type": "local",
      "command": ["npx", "-y", "@kieksme/listmonk-mcp", "--stdio"],
      "environment": {
        "LISTMONK_URL": "https://newsletter.example.com",
        "LISTMONK_API_USER": "my-api-user",
        "LISTMONK_API_TOKEN": "xxxxxxxx"
      },
      "enabled": true
    }
  }
}

远程（HTTP），在服务器运行后：

{
  "mcp": {
    "listmonk": {
      "type": "remote",
      "url": "http://localhost:3000/mcp",
      "enabled": true
    }
  }
}

关于 enabled 的说明： 这个标志是 OpenCode 自己的客户端开关——它只是为该客户端打开或关闭整个服务器连接，与暴露哪些 listmonk 工具/类别无关。在远程（HTTP）配置中，若要限制这个特定客户端能看到哪些工具（无需重启服务器或改动 LISTMONK_ENABLED_TOOLS），请将 tools 查询参数附加到 url 本身：

{
  "mcp": {
    "listmonk": {
      "type": "remote",
      "url": "http://localhost:3000/mcp?tools=subscribers,campaigns",
      "enabled": true
    }
  }
}

在本地（stdio）配置中，请在 environment 中设置 LISTMONK_ENABLED_TOOLS——完整的选择器语法请参阅选择可用的工具。

LM Studio

一键安装（本地/stdio，其中包含占位凭据，之后你需要在 LM Studio 的 MCP 设置中填写）：

或者手动配置，通过 ~/.lmstudio/mcp.json（程序选项卡 → 安装 → 编辑 mcp.json）——本地（stdio）：

{
  "mcpServers": {
    "listmonk": {
      "command": "npx",
      "args": ["-y", "@kieksme/listmonk-mcp", "--stdio"],
      "env": {
        "LISTMONK_URL": "https://newsletter.example.com",
        "LISTMONK_API_USER": "my-api-user",
        "LISTMONK_API_TOKEN": "xxxxxxxx"
      }
    }
  }
}

远程（HTTP），在服务器运行后：

{
  "mcpServers": {
    "listmonk": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

ChatGPT

ChatGPT 的连接器（设置 → 连接器 → 创建，适用于支持 MCP 的付费套餐）只接受可公开访问的 HTTP URL——ChatGPT 运行在云端，无法启动本地 stdio 进程，因此远程配置是唯一选择。将服务器部署到具有公共 URL 的主机上（参见 Docker），或为你的本地实例建立隧道（例如 ngrok http 3000），然后将 https://<your-host>/mcp 注册为连接器 URL。如果你设置了 MCP_SERVER_AUTH_TOKEN，ChatGPT 的连接器设置允许你在 URL 之外再提供一个 bearer token。

功能特性

• 完整的 API 覆盖：订阅者、营销活动、列表、模板、媒体、退信、导入、设置、维护、事务性消息、公开订阅、日志、管理以及仪表盘/杂项端点。

• 选择性工具加载——只启用你实际需要的类别/工具，这样 LLM 的上下文就不会一下子被全部 72 个工具定义塞满。

• 两种传输方式，一个包： stdio 用于客户端启动的本地进程，无状态的 Streamable HTTP 用于远程部署（无会话状态，易于在负载均衡器后面水平扩展）。

• 在 /mcp 前面提供可选的 bearer-token 门禁（仅限 HTTP 传输——stdio 没有网络监听器需要门禁）。

运行服务器

本地（stdio）

通常你不需要手动启动它——你的 MCP 客户端会按照上文连接你的 MCP 客户端中的配置来启动它。若要手动运行（例如在客户端之外做冒烟检查），请传入 --stdio 或设置 MCP_TRANSPORT=stdio：

LISTMONK_URL=https://newsletter.example.com \
LISTMONK_API_USER=my-api-user \
LISTMONK_API_TOKEN=xxxxxxxx \
npx @kieksme/listmonk-mcp --stdio

该进程在 stdout 上使用 MCP JSON-RPC 通信，并将日志输出到 stderr——当它的 stdin 关闭时（即父客户端断开连接时）退出。LISTMONK_ENABLED_TOOLS 仍然用于选择注册哪些工具，但在此模式下没有按请求覆盖的机制：一个客户端进程，在其生命周期内对应一套固定的工具集。

远程（HTTP）

LISTMONK_URL=https://newsletter.example.com \
LISTMONK_API_USER=my-api-user \
LISTMONK_API_TOKEN=xxxxxxxx \
npx @kieksme/listmonk-mcp
# or
pnpm dlx @kieksme/listmonk-mcp

MCP 端点是 POST http://localhost:3000/mcp（流式 HTTP，无状态——无需会话协商）。

Docker

已发布的镜像（ghcr.io/kieksme/mcp-listmonk:latest）支持两种传输方式——它与 npx 使用相同的入口点，因此上面的标志同样适用。

远程（HTTP）——发布端口：

docker run -p 3000:3000 \
  -e LISTMONK_URL=https://newsletter.example.com \
  -e LISTMONK_API_USER=my-api-user \
  -e LISTMONK_API_TOKEN=xxxxxxxx \
  -e LISTMONK_ENABLED_TOOLS='["subscribers","campaigns"]' \
  ghcr.io/kieksme/mcp-listmonk:latest

本地（stdio）——保持 stdin 附加（-i），而不是发布端口；如果你更愿意运行容器而不是让 npx 拉取包，这就是你要放在客户端 command/args 后面的内容（例如将 docker 作为 command）：

docker run -i --rm \
  -e LISTMONK_URL=https://newsletter.example.com \
  -e LISTMONK_API_USER=my-api-user \
  -e LISTMONK_API_TOKEN=xxxxxxxx \
  ghcr.io/kieksme/mcp-listmonk:latest --stdio

配置

启动服务器时设置以下环境变量：

安全说明： LISTMONK_API_USER/LISTMONK_API_TOKEN 用于此服务器向Listmonk进行身份验证，而不是 MCP 客户端向此服务器进行身份验证。如果没有 MCP_SERVER_AUTH_TOKEN，任何能够访问该端口的人都能以所配置 API 用户拥有的任何权限范围获得完整的 Listmonk 访问权限。建议在 Listmonk 中创建一个最低权限的 API 用户，其权限范围仅限于你打算启用的类别。

选择可用的工具

LISTMONK_ENABLED_TOOLS 接受一个 JSON 数组（或逗号分隔的字符串），其条目不区分大小写，要么是：

• 类别名称：subscribers、campaigns、templates、lists、media、import、bounces、settings、maintenance、public、transactional、logs、admin、miscellaneous——启用该类别中的每个工具，或

• 精确的工具名称：例如 listmonk_get_subscriber——仅启用这一个工具。

# Only subscriber management tools
LISTMONK_ENABLED_TOOLS='["subscribers"]'

# A mix of a whole category plus one extra tool
LISTMONK_ENABLED_TOOLS='["campaigns","listmonk_get_health"]'

# Comma-separated form also works
LISTMONK_ENABLED_TOOLS=subscribers,campaigns

保持未设置（或 []）以暴露全部 72 个工具。

按请求覆盖（仅限远程/HTTP）： 单个已部署实例还可以在不重启的情况下，通过 POST /mcp 请求上的 X-Listmonk-Enabled-Tools 头或 ?tools= 查询字符串，为不同客户端提供不同的工具集——选择器语法与上述相同。这仅针对该一个请求覆盖 LISTMONK_ENABLED_TOOLS。本地/stdio 传输没有等效机制：每个 stdio 进程都是为每个客户端全新生成的，因此只需在该客户端自己的 env/environment 配置中设置 LISTMONK_ENABLED_TOOLS 即可。

由于查询字符串只是 URL 的一部分，这是为某个特定客户端（例如 opencode.json、.mcp.json 或 .cursor/mcp.json 中的一个条目）提供精简工具集的最简单方式，同时其他客户端继续以完整（或不同）工具集访问同一服务器——只需将该客户端的 url 设置为 http://localhost:3000/mcp?tools=subscribers,campaigns，而无需添加服务器级环境变量或再部署一个实例。支持自定义头的客户端可以改用 X-Listmonk-Enabled-Tools，这样 URL 本身保持整洁。

工具目录（72 个工具）

subscribers（17 个）

listmonk_list_subscribers, listmonk_create_subscriber, listmonk_get_subscriber, listmonk_update_subscriber, listmonk_delete_subscriber, listmonk_delete_subscribers_by_ids, listmonk_manage_subscriber_lists_bulk, listmonk_manage_subscriber_list_membership, listmonk_blocklist_subscribers_bulk, listmonk_blocklist_subscriber, listmonk_export_subscriber, listmonk_get_subscriber_bounces, listmonk_delete_subscriber_bounces, listmonk_send_subscriber_optin, listmonk_delete_subscribers_by_query, listmonk_blocklist_subscribers_by_query, listmonk_manage_subscriber_lists_by_query

campaigns（14 个）

listmonk_list_campaigns, listmonk_create_campaign, listmonk_get_campaign, listmonk_update_campaign, listmonk_delete_campaign, listmonk_get_running_campaign_stats, listmonk_get_campaign_analytics, listmonk_get_campaign_preview, listmonk_preview_campaign_draft, listmonk_preview_campaign_text, listmonk_update_campaign_status, listmonk_update_campaign_archive, listmonk_convert_campaign_content, listmonk_send_campaign_test

templates（8 个）

listmonk_list_templates, listmonk_create_template, listmonk_get_template, listmonk_update_template, listmonk_delete_template, listmonk_preview_template_draft, listmonk_preview_template, listmonk_set_default_template

lists（5 个）

listmonk_list_lists, listmonk_create_list, listmonk_get_list, listmonk_update_list, listmonk_delete_list

media（4 个）

listmonk_list_media, listmonk_upload_media, listmonk_get_media, listmonk_delete_media

import（4 个）

listmonk_get_import_status, listmonk_import_subscribers, listmonk_stop_import_subscribers, listmonk_get_import_logs

bounces（4 个）

listmonk_list_bounces, listmonk_delete_bounces, listmonk_get_bounce, listmonk_delete_bounce

settings（3 个）

listmonk_get_settings, listmonk_update_settings, listmonk_test_smtp_settings

maintenance（3 个）

listmonk_delete_gc_subscribers, listmonk_delete_gc_campaign_analytics, listmonk_delete_unconfirmed_subscriptions

public（2 个）

listmonk_get_public_lists, listmonk_create_public_subscription

transactional（1 个）

listmonk_send_transactional_message

logs（1 个）

listmonk_get_logs

admin（1 个）

listmonk_reload_app

miscellaneous（5 个）

listmonk_get_health, listmonk_get_server_config, listmonk_get_i18n_lang, listmonk_get_dashboard_charts, listmonk_get_dashboard_counts

关于几个不太直观的工具的说明

• 批量/查询订阅者操作（listmonk_delete_subscribers_by_query、listmonk_blocklist_subscribers_by_query、listmonk_manage_subscriber_lists_by_query）针对 Listmonk SQL 过滤器表达式运行，并对每一个匹配的订阅者执行操作，没有预览步骤。请始终先使用相同的 query 调用 listmonk_list_subscribers 来检查匹配数量。

• 活动预览/内容工具被有意拆分为四个不同的工具，因为 Listmonk 为它们提供了四个不同的端点：listmonk_get_campaign_preview 按当前保存的状态渲染活动；listmonk_preview_campaign_draft 和 listmonk_preview_campaign_text 渲染未保存的正文而不持久化任何内容；listmonk_convert_campaign_content 执行并持久化格式转换（例如 markdown → HTML）——尽管功能领域相似，但它不是预览。

• listmonk_send_campaign_test 首先获取活动当前已保存的状态，并且只覆盖你显式传入的字段，以避免意外清空 Listmonk 自身 API 原本会静默地用空值覆盖的字段。

贡献

想从源码构建、运行测试套件，或了解发布流程？请参阅 CONTRIBUTING.md。

许可证

MIT © kieksme GbR