Listmonk MCP

🚀 Listmonk MCP Server

Listmonk用のMCP（Model Context Protocol）サーバーの実装です。ニュースレターやメーリングリストの管理機能にプログラムからアクセスできるようになります。

🚀 クイックスタート

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

# Listmonkにアクセス: http://localhost:9000
# デフォルトの認証情報: admin / listmonk

2. APIユーザーとトークンの作成

1. http://localhost:9000/admin でListmonkの管理インターフェースにアクセスします。
2. デフォルトの認証情報 admin / listmonk でログインします。
3. Admin → Users (http://localhost:9000/admin/users) に移動します。
4. 新しいAPIユーザーを作成します。
   • "Add new" をクリックします。
   • ユーザー名（例: api-user）を入力します。
   • 適切なロール/パーミッションを割り当てます。
   • ユーザーを保存します。
5. APIトークンを生成します。
   • 作成したユーザーをクリックします。
   • "Generate API token" をクリックします。
   • 生成されたトークンをコピーします。

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 でAPIアクセスをテストします。
• 一般的なエラー: "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リソース: 加入者、リスト、キャンペーン、テンプレートのデータに簡単にアクセスできます。
• 非同期操作: 最新のasync/awaitパターンで構築されています。
• 型安全性: 完全な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サーバーは完全に実装され、機能しています。

目標

Model Context Protocolを通じてLLMやAIアシスタントがListmonkインスタンスとやり取りできるMCPサーバーを作成することです。これにより以下のことが可能になります。

• 加入者管理（加入者の追加、削除、更新）
• メーリングリスト操作（リストの作成、管理）
• キャンペーン管理（ニュースレターの作成、送信）
• 分析とレポートへのアクセス
• テンプレートとコンテンツの管理

アーキテクチャ

このサーバーはMCPプロトコルとListmonkのREST APIを橋渡しし、AIモデルがListmonkインストールとやり取りするための標準化されたインターフェースを提供します。