@kieksme/listmonk-mcp

Un servidor MCP (Model Context Protocol) que expone la API REST completa de Listmonk (72 herramientas en 14 categorías) a clientes LLM compatibles con MCP — como un proceso local stdio que tu cliente lanza por sí mismo, o como un despliegue remoto Streamable HTTP al que cualquier número de clientes puede conectarse.

Construido contra la especificación OpenAPI de Listmonk.

Quickstart

Local: deja que tu cliente MCP lance el servidor por sí mismo a través de stdio — nada que ejecutar a mano, ningún puerto que abrir. Añádelo a la configuración de tu cliente (Claude Code se muestra aquí; consulta Conectando tu cliente MCP más abajo para Cursor, VS Code, Claude Desktop, OpenCode, LM Studio y 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

Remoto: inicia el servidor una vez, accesible por HTTP para cualquier número de clientes:

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

Consulta Ejecutar el servidor para más detalle sobre ambos modos, incluido Docker.

Related MCP server: listmonk-mcp-bridge

Conectando tu cliente MCP

Cada cliente de abajo admite dos configuraciones — elige una:

• Local (stdio): el cliente lanza npx @kieksme/listmonk-mcp --stdio como subproceso y habla MCP a través de su stdin/stdout. No hay que mantener un servidor en ejecución, ni puerto, ni problemas de accesibilidad — esta suele ser la opción más sencilla para un único cliente local.

• Remoto (HTTP): tú mismo ejecutas el servidor (consulta Ejecutar el servidor) y el cliente se conecta a su URL. Necesario cuando varios clientes comparten una instancia del servidor, o cuando el servidor se ejecuta en un lugar distinto de tu máquina.

Usar pnpm en lugar de npx para la configuración local/stdio: todos los ejemplos locales (stdio) de abajo usan command: "npx" con args: ["-y", "@kieksme/listmonk-mcp", "--stdio"]. Si prefieres pnpm, cambia a command: "pnpm" con args: ["dlx", "@kieksme/listmonk-mcp", "--stdio"] — y elimina el -y. -y es la opción de npx para "omitir el mensaje de confirmación de instalación"; pnpm dlx no tiene tal mensaje, así que no acepta -y en absoluto y sale inmediatamente con ERROR Unknown option: 'y' (apareciendo ante el cliente como un genérico "Connection closed", ya que el proceso muere antes de hablar MCP). El mismo cambio aplica a cualquier forma de CLI de abajo que empiece con npx -y — reemplázala con pnpm dlx (sin -y).

Nota de accesibilidad para la configuración remota/HTTP: un cliente solo necesita http://localhost:3000 si se ejecuta en la misma máquina que el servidor. Claude Code, Cursor, VS Code, OpenCode y LM Studio son herramientas locales, así que localhost funciona directamente. Claude Desktop es una aplicación local y normalmente también puede alcanzar localhost. ChatGPT y Claude.ai (las aplicaciones web) se ejecutan en la nube y no pueden alcanzar tu localhost — para usar este servidor con ellos tendrías que desplegarlo en algún lugar accesible desde internet (o tunelizarlo, p. ej. con ngrok http 3000) y usar esa URL pública. Los conectores de ChatGPT son solo HTTP, por lo que no tiene opción local/stdio más abajo.

Claude Code

Local (stdio), a nivel de proyecto mediante .mcp.json en la raíz de tu repositorio:

{
  "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"
      }
    }
  }
}

O desde la 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

Remoto (HTTP), una vez que el servidor esté en ejecución (consulta Ejecutar el servidor):

{
  "mcpServers": {
    "listmonk": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

claude mcp add --transport http listmonk http://localhost:3000/mcp

Si configuras MCP_SERVER_AUTH_TOKEN en el servidor, añade la cabecera: claude mcp add --transport http listmonk http://localhost:3000/mcp --header "Authorization: Bearer <token>".

Cursor

Instalación con un clic (local/stdio, con credenciales de ejemplo que tendrás que rellenar después en los ajustes de MCP de Cursor):

O configúralo manualmente — local (stdio), mediante .cursor/mcp.json en la raíz de tu repositorio (o globalmente en ~/.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"
      }
    }
  }
}

Remoto (HTTP), una vez que el servidor esté en ejecución:

{
  "mcpServers": {
    "listmonk": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Si configuras MCP_SERVER_AUTH_TOKEN en el servidor, pásalo como cabecera:

{
  "mcpServers": {
    "listmonk": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

También puedes añadir cualquiera de las dos configuraciones mediante Cursor Settings → MCP → Add new MCP server.

VS Code

Instalación con un clic (local/stdio, con credenciales de ejemplo que tendrás que rellenar después en los ajustes de MCP de VS Code):

O configúralo manualmente — local (stdio), mediante .vscode/mcp.json en la raíz de tu repositorio:

{
  "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"
      }
    }
  }
}

Remoto (HTTP), una vez que el servidor esté en ejecución (type es obligatorio aquí, ya que no hay command del que inferirlo):

{
  "servers": {
    "listmonk": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Claude Desktop

Local (stdio), en 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"
      }
    }
  }
}

Remoto (HTTP): Settings → Connectors → Add custom connector, y pega http://localhost:3000/mcp como URL (el servidor ya debe estar en ejecución). Si el archivo de configuración de tu versión de Claude Desktop admite servidores remotos directamente, la entrada equivalente es:

{
  "mcpServers": {
    "listmonk": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

OpenCode

Local (stdio), en opencode.json (configuración de proyecto o global):

{
  "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
    }
  }
}

Remoto (HTTP), una vez que el servidor esté en ejecución:

{
  "mcp": {
    "listmonk": {
      "type": "remote",
      "url": "http://localhost:3000/mcp",
      "enabled": true
    }
  }
}

Nota sobre enabled: esta opción es el interruptor propio de OpenCode en el lado del cliente — simplemente activa o desactiva toda la conexión al servidor para ese cliente y no tiene nada que ver con qué herramientas/categorías de listmonk se exponen. En la configuración remota (HTTP), para limitar qué herramientas ve este cliente en particular (sin reiniciar el servidor ni tocar LISTMONK_ENABLED_TOOLS), añade el parámetro de consulta tools a la propia url:

{
  "mcp": {
    "listmonk": {
      "type": "remote",
      "url": "http://localhost:3000/mcp?tools=subscribers,campaigns",
      "enabled": true
    }
  }
}

En la configuración local (stdio), establece LISTMONK_ENABLED_TOOLS en environment en su lugar — consulta Seleccionar qué herramientas están disponibles para conocer la sintaxis completa del selector.

LM Studio

Instalación con un clic (local/stdio, con credenciales de ejemplo que tendrás que rellenar después en los ajustes de MCP de LM Studio):

O configúralo manualmente, mediante ~/.lmstudio/mcp.json (Program tab → Install → Edit mcp.json) — local (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"
      }
    }
  }
}

Remoto (HTTP), una vez que el servidor esté en ejecución:

{
  "mcpServers": {
    "listmonk": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

ChatGPT

Los conectores de ChatGPT (Settings → Connectors → Create, disponibles en los planes de pago que admiten MCP) solo aceptan una URL HTTP accesible públicamente — ChatGPT se ejecuta en la nube y no puede lanzar un proceso stdio local, así que la configuración remota es la única opción. Despliega el servidor (consulta Docker) en un host con URL pública, o tuneliza tu instancia local (p. ej. ngrok http 3000), y luego registra https://<your-host>/mcp como URL del conector. Si configuras MCP_SERVER_AUTH_TOKEN, la configuración de conectores de ChatGPT te permite proporcionar un token de portador junto con la URL.

Características

• Cobertura completa de la API: suscriptores, campañas, listas, plantillas, medios, rebotes, importación, ajustes, mantenimiento, mensajes transaccionales, suscripción pública, registros, administración y endpoints de panel/misceláneos.

• Carga selectiva de herramientas — habilita solo las categorías/herramientas que realmente necesitas, para que el contexto del LLM no se inunde con las 72 definiciones de herramientas a la vez.

• Dos transportes, un solo paquete: stdio para un proceso local lanzado por el cliente, Streamable HTTP sin estado para un despliegue remoto (sin estado de sesión, fácil de escalar horizontalmente detrás de un balanceador de carga).

• Puerta opcional de token de portador delante de /mcp (solo transporte HTTP — stdio no tiene listener de red que proteger).

Ejecutar el servidor

Local (stdio)

Normalmente no lo inicias a mano — tu cliente MCP lo lanza según la configuración en Conectando tu cliente MCP más arriba. Para ejecutarlo manualmente (p. ej. para comprobarlo fuera de un cliente), pasa --stdio o establece MCP_TRANSPORT=stdio:

LISTMONK_URL=https://newsletter.example.com \
LISTMONK_API_USER=my-api-user \
LISTMONK_API_TOKEN=xxxxxxxx \
npx @kieksme/listmonk-mcp --stdio

El proceso habla MCP JSON-RPC por stdout y registra en stderr — sale cuando su stdin se cierra (es decir, cuando el cliente padre se desconecta). LISTMONK_ENABLED_TOOLS sigue seleccionando qué herramientas se registran, pero no hay anulación por solicitud en este modo: un proceso de cliente, un conjunto fijo de herramientas durante toda su vida.

Remoto (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

El endpoint de MCP es POST http://localhost:3000/mcp (HTTP streamable, sin estado — no se necesita negociación de sesión).

Docker

La imagen publicada (ghcr.io/kieksme/mcp-listmonk:latest) admite ambos transportes — es el mismo entrypoint que npx, así que las opciones de arriba se aplican de la misma manera.

Remoto (HTTP) — publica el puerto:

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

Local (stdio) — mantén stdin conectado (-i) en lugar de publicar un puerto; esto es lo que pondrías detrás de command/args de un cliente (p. ej. docker como comando) si prefieres ejecutar el contenedor en lugar de que npx descargue el paquete:

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

Configuración

Establece estas variables de entorno al iniciar el servidor:

Nota de seguridad: LISTMONK_API_USER/LISTMONK_API_TOKEN autentican este servidor ante Listmonk, no a los clientes MCP ante este servidor. Sin MCP_SERVER_AUTH_TOKEN, cualquiera que pueda alcanzar el puerto obtiene acceso completo a Listmonk con el alcance que tenga el usuario de API configurado. Prefiera crear un usuario de API con privilegios mínimos en Listmonk limitado solo a las categorías que pretenda habilitar.

Selección de las herramientas disponibles

LISTMONK_ENABLED_TOOLS acepta una matriz JSON (o cadena separada por comas) cuyas entradas son, sin distinción de mayúsculas y minúsculas, o bien:

• un nombre de categoría: subscribers, campaigns, templates, lists, media, import, bounces, settings, maintenance, public, transactional, logs, admin, miscellaneous — habilita todas las herramientas de esa categoría, o

• un nombre de herramienta exacto: p. ej. listmonk_get_subscriber — habilita solo esa herramienta.

# 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

Déjelo sin definir (o []) para exponer las 72 herramientas.

Anulación por solicitud (solo remoto/HTTP): una única instancia desplegada también puede servir diferentes conjuntos de herramientas a diferentes clientes sin reiniciar, mediante la cabecera X-Listmonk-Enabled-Tools o la cadena de consulta ?tools= en la solicitud POST /mcp — la misma sintaxis de selectores que arriba. Esto anula LISTMONK_ENABLED_TOOLS solo para esa solicitud. No hay equivalente para el transporte local/stdio: cada proceso stdio se crea de nuevo por cliente, así que simplemente establezca LISTMONK_ENABLED_TOOLS en la configuración env/environment de ese cliente.

Dado que la cadena de consulta es solo parte de la URL, esta es la forma más sencilla de dar a un cliente concreto (p. ej. una entrada en opencode.json, .mcp.json o .cursor/mcp.json) un conjunto de herramientas reducido mientras otros clientes siguen usando el mismo servidor con el conjunto completo (o uno diferente) — basta con establecer la url de ese cliente en http://localhost:3000/mcp?tools=subscribers,campaigns en lugar de añadir variables de entorno para todo el servidor o levantar una segunda instancia. Los clientes que admiten cabeceras personalizadas pueden usar X-Listmonk-Enabled-Tools en su lugar, lo que mantiene limpia la propia URL.

Catálogo de herramientas (72 herramientas)

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

Notas sobre algunas herramientas poco evidentes

• Operaciones masivas/por consulta sobre suscriptores (listmonk_delete_subscribers_by_query, listmonk_blocklist_subscribers_by_query, listmonk_manage_subscriber_lists_by_query) se ejecutan contra una expresión de filtro SQL de Listmonk y actúan sobre todos los suscriptores que coincidan sin paso de vista previa. Llame siempre primero a listmonk_list_subscribers con la misma query para comprobar el número de coincidencias.

• Las herramientas de vista previa/contenido de campañas están divididas intencionadamente en cuatro herramientas distintas porque Listmonk expone cuatro endpoints distintos para ellas: listmonk_get_campaign_preview renderiza la campaña tal como está guardada actualmente; listmonk_preview_campaign_draft y listmonk_preview_campaign_text renderizan un cuerpo no guardado sin persistir nada; listmonk_convert_campaign_content realiza y persiste una conversión de formato (p. ej. markdown → HTML) — no es una vista previa a pesar de la similitud.

• listmonk_send_campaign_test obtiene primero el estado guardado actual de la campaña y solo anula los campos que usted pasa explícitamente, para evitar vaciar accidentalmente campos que la propia API de Listmonk sobrescribiría silenciosamente con valores vacíos.

Contribuciones

¿Quiere compilar desde el código fuente, ejecutar la suite de pruebas o entender el proceso de publicación? Consulte CONTRIBUTING.md.

Licencia

MIT © kieksme GbR