Listmonk MCP

Listmonk MCP サーバー

セルフホスト可能なニュースレターおよびメーリングリスト管理ツール、Listmonk 用の MCP サーバーです。AI エージェント（Claude Code、Claude Desktop、Cursor、Cline、VS Code など）を使って、購読者、メーリングリスト、キャンペーン、テンプレート、メディアを管理し、Listmonk インスタンスからトランザクションメールを送信できます。

Rohan Verma による rhnvrm/listmonk-mcp の TypeScript 移植版で、ファイルベースのテンプレート、キャンペーン本文の編集、強化されたファイルアクセス機能を追加しています。

TypeScript で記述され、Bun 上で動作します。

Русская версия

機能

• 購読者： 追加、更新、削除、ステータス変更、Listmonk の SQL クエリによる検索、ID またはメールアドレスによる検索。
• メーリングリスト： 作成、更新、削除、一覧表示、メンバー一覧の表示。
• キャンペーン： 作成、更新、プレビュー、即時送信、予約。プレーンテキスト、正規表現、一括置換で本文を編集できます。
• テンプレート： 作成、更新、削除、読み取り。大きな HTML 本文（たとえば、MJML のエクスポート）はファイルから直接読み込めます。
• トランザクションメール： カスタムデータを指定して、1 人の受信者に tx テンプレートを送信します。
• メディア： アップロード、名前変更、削除、一覧表示。

必要条件

• Bun 1.1 以降。
• API ユーザーを設定した Listmonk。Listmonk の管理画面で Users を開き、API タイプのユーザーを作成して、そのトークンをコピーします。エージェントに必要な権限だけを持つロールを割り当ててください。

クイックスタート

ワンクリックでインストールできます（インストール後、クライアントの 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> は env ファイルを読み込み、-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
キャンペーン	get_campaigns、get_campaign、get_campaign_preview、create_campaign、update_campaign、send_campaign、schedule_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 から読み込む購読者名、キャンペーン本文、その他のデータには、見知らぬ人が書いた指示（プロンプトインジェクション）が含まれている可能性があります。この制限がなければ、そのようなテキストによってエージェントが ~/.ssh や .env を読み取り、メールで送信するおそれがあります。
• 送信ツールの承認を有効にしておいてください。 send_campaign、schedule_campaign、send_transactional_email は実際にメールを送信します。クライアントでこれらを自動承認しないでください。
• エージェントに必要な権限だけに制限したロールを持つ専用の API ユーザーを使用し、管理者アカウントは使用しないでください。
• トークンを共有ファイルに含めないでください。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