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 安裝實例的交互提供標準化接口。