@kieksme/listmonk-mcp

MCP（Model Context Protocol）互換のLLMクライアントに対して、Listmonk のREST API全体（14カテゴリ・72ツール）を公開するMCPサーバーです。クライアント自身が起動するローカル 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クライアントの接続

以下の各クライアントは2つのセットアップに対応しています。どちらかを選んでください：

• ローカル (stdio): クライアントが npx @kieksme/listmonk-mcp --stdio をサブプロセスとして自ら起動し、その標準入力/標準出力を介してMCP通信を行います。サーバーを常駐させる必要も、ポートを開く必要も、到達性の心配もありません。通常は単一のローカルクライアントにとって最もシンプルな既定の選択肢です。

• リモート (HTTP): サーバーを自分で実行し（サーバーの実行 を参照）、クライアントはそのURLに接続します。複数のクライアントが1つのサーバーインスタンスを共有する場合や、サーバーを自分のマシン以外で実行する場合に必要です。

ローカル/stdioセットアップでnpxの代わりにpnpmを使う場合: 以下のローカル（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）、サーバーが起動したら（ここでは command から推測できないため type が必要です）：

{
  "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）：設定 → コネクタ → カスタムコネクタを追加 で、URLとして http://localhost:3000/mcp を貼り付けます（サーバーがすでに起動している必要があります）。お使いの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 を変更したりせずに）、url 自体に tools クエリパラメータを追加します：

{
  "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 経由（Programタブ → インストール → 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と一緒にベアラートークンを指定できます。

機能

• 完全なAPIカバレッジ：サブスクライバー、キャンペーン、リスト、テンプレート、メディア、バウンス、インポート、設定、メンテナンス、トランザクションメール、公開サブスクリプション、ログ、管理、ダッシュボード/その他のエンドポイント。

• 選択的ツールロード — 実際に必要なカテゴリ/ツールだけを有効にできるため、LLMのコンテキストが72個すべてのツール定義で一度に埋め尽くされることはありません。

• 2つのトランスポート、1つのパッケージ: クライアントが起動するローカルプロセス用のstdio、リモートデプロイ用のステートレスStreamable HTTP（セッション状態がなく、ロードバランサーの背後で水平スケールしやすい）。

• /mcp の前のオプションのベアラートークンゲート（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 は引き続き登録するツールを選択しますが、このモードではリクエストごとの上書きはありません。1つのクライアントプロセスにつき、その存続期間中は1つの固定されたツールセットです。

リモート (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）の後ろに置くものです：

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 — その 1 つのツールだけを有効にします。

# 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 のみ）: デプロイされた単一のインスタンスは、再起動なしで、ヘッダー X-Listmonk-Enabled-Tools または POST /mcp リクエストのクエリ文字列 ?tools= を使用して、クライアントごとに異なるツールセットを提供することもできます — セレクタ構文は上記と同じです。これはその 1 つのリクエストについてのみ LISTMONK_ENABLED_TOOLS を上書きします。ローカル/stdio トランスポートには同等のものはありません。各 stdio プロセスはクライアントごとに新しく生成されるため、代わりにそのクライアント自身の env/environment 設定で LISTMONK_ENABLED_TOOLS を設定してください。

クエリ文字列は URL の一部にすぎないため、これは特定の 1 つのクライアント（例: opencode.json、.mcp.json、または .cursor/mcp.json 内の 1 エントリ）に縮小されたツールセットを提供しつつ、他のクライアントは同じサーバーに対してフル（または別の）セットでアクセスし続ける最も簡単な方法です — サーバー全体の環境変数を追加したり、2 つ目のインスタンスを立ち上げたりする代わりに、そのクライアントの 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 がそれぞれに 4 つの異なるエンドポイントを公開しているため、意図的に 4 つの異なるツールに分割されています: 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