@kieksme/listmonk-mcp

MCP-сервер (Model Context Protocol), открывающий полный REST API Listmonk (72 инструмента в 14 категориях) для MCP-совместимых LLM-клиентов — как локальный процесс stdio, который ваш клиент запускает сам, или как удалённое развёртывание Streamable HTTP, к которому может подключиться любое количество клиентов.

Создан на основе спецификации OpenAPI Listmonk.

Быстрый старт

Локально: позвольте вашему MCP-клиенту запустить сервер самостоятельно через stdio — ничего не нужно запускать вручную, не нужно открывать порт. Добавьте его в конфигурацию вашего клиента (здесь показан Claude Code; см. Подключение вашего MCP-клиента ниже для Cursor, VS Code, Claude Desktop, OpenCode, LM Studio и ChatGPT):

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 как подпроцесс и общается по MCP через его stdin/stdout. Не нужно держать сервер запущенным, не нужен порт, нет проблем с доступностью — как правило, это более простой вариант по умолчанию для одного локального клиента.

• Удалённо (HTTP): вы сами запускаете сервер (см. Запуск сервера), и клиент подключается к его URL. Требуется, когда несколько клиентов используют один экземпляр сервера или сервер работает не на вашей машине.

Использование pnpm вместо npx для локальной настройки (stdio): каждый локальный пример (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' (что проявляется для клиента как общее «Connection closed», поскольку процесс умирает, так и не начав общение по MCP). Та же замена применима к любой форме CLI ниже, которая начинается с npx -y — замените её на pnpm dlx (без -y).

Примечание о доступности для удалённой настройки (HTTP): клиенту нужен http://localhost:3000 только если он работает на той же машине, что и сервер. Claude Code, Cursor, VS Code, OpenCode и LM Studio — это локальные инструменты, поэтому localhost работает напрямую. Claude Desktop — локальное приложение и обычно тоже может обратиться к localhost. ChatGPT и Claude.ai (веб-приложения) работают в облаке и не могут обратиться к вашему 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, с заготовками учётных данных, которые вам нужно будет заполнить позже в настройках MCP в Cursor):

Или настройте вручную — локально (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 Settings → MCP → Add new MCP server.

VS Code

Установка в один клик (локально/stdio, с заготовками учётных данных, которые вам нужно будет заполнить позже в настройках MCP в VS Code):

Или настройте вручную — локально (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): Settings → Connectors → Add custom connector, и вставьте 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) вместо этого задайте LISTMONK_ENABLED_TOOLS в environment — полный синтаксис селектора см. в разделе Выбор доступных инструментов.

LM Studio

Установка в один клик (локально/stdio, с заготовками учётных данных, которые вам нужно будет заполнить позже в настройках MCP в LM Studio):

Или настройте вручную через ~/.lmstudio/mcp.json (вкладка Program → Install → Edit 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 (Settings → Connectors → Create, доступны на платных тарифах, поддерживающих MCP) принимают только публично доступный HTTP URL — ChatGPT работает в облаке и не может запустить локальный процесс stdio, так что удалённая настройка — единственный вариант. Разверните сервер (см. Docker) на хосте с публичным URL или пробросьте туннель к вашему локальному экземпляру (например, ngrok http 3000), затем укажите https://<your-host>/mcp как URL коннектора. Если вы задали MCP_SERVER_AUTH_TOKEN, настройка коннектора ChatGPT позволяет указать bearer-токен вместе с URL.

Возможности

• Полное покрытие API: подписчики, кампании, списки, шаблоны, медиа, отказы, импорт, настройки, обслуживание, транзакционные сообщения, публичная подписка, журналы, администрирование и конечные точки панели управления/прочие.

• Выборочная загрузка инструментов — включайте только те категории/инструменты, которые вам действительно нужны, чтобы контекст LLM не был переполнен всеми 72 определениями инструментов сразу.

• Два транспорта в одном пакете: stdio для локального процесса, запускаемого клиентом, и stateless Streamable HTTP для удалённого развёртывания (без состояния сессии, легко масштабируется горизонтально за балансировщиком нагрузки).

• Опциональная защита /mcp bearer-токеном (только для 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

Процесс общается по MCP JSON-RPC через stdout и пишет логи в 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 (streamable 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) вместо публикации порта; именно это вы поместите в command/args клиента (например, docker как команду), если предпочитаете запускать контейнер, а не получать пакет через npx:

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 любой, кто может получить доступ к порту, получает полный доступ к Listmonk в том объёме, который доступен настроенному API-пользователю. Предпочтительнее создать в 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 инструмента.

Переопределение для отдельного запроса (только remote/HTTP): один развёрнутый экземпляр может также обслуживать разные наборы инструментов для разных клиентов без перезапуска — через заголовок X-Listmonk-Enabled-Tools или строку запроса ?tools= в запросе POST /mcp — синтаксис селекторов тот же, что и выше. Это переопределяет LISTMONK_ENABLED_TOOLS только для этого одного запроса. Для локального/stdio транспорта эквивалента нет: каждый stdio-процесс порождается заново для каждого клиента, поэтому просто задайте LISTMONK_ENABLED_TOOLS в конфигурации env/environment самого клиента.

Поскольку строка запроса — это просто часть 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) выполняются на основе SQL-выражения фильтра Listmonk и действуют на каждого подходящего подписчика без этапа предпросмотра. Всегда сначала вызывайте listmonk_list_subscribers с тем же query, чтобы проверить количество совпадений.

• Инструменты предпросмотра и контента кампаний намеренно разделены на четыре отдельных инструмента, потому что Listmonk предоставляет для них четыре отдельных эндпоинта: listmonk_get_campaign_preview отображает кампанию в текущем сохранённом виде; listmonk_preview_campaign_draft и listmonk_preview_campaign_text отображают несохранённое тело без сохранения чего-либо; listmonk_convert_campaign_content выполняет и сохраняет конвертацию формата (например, markdown → HTML) — это не предпросмотр, несмотря на похожую область применения.

• listmonk_send_campaign_test сначала получает текущее сохранённое состояние кампании и переопределяет только те поля, которые вы явно передаёте, чтобы случайно не обнулить поля, которые собственный API Listmonk в противном случае молча перезаписал бы пустыми значениями.

Участие в разработке

Хотите собрать проект из исходников, запустить набор тестов или разобраться в процессе выпуска? Смотрите CONTRIBUTING.md.

Лицензия

MIT © kieksme GbR