@kieksme/listmonk-mcp

Ein MCP-Server (Model Context Protocol), der die vollständige Listmonk REST-API (72 Tools in 14 Kategorien) für MCP-kompatible LLM-Clients bereitstellt — als lokalen stdio-Prozess, den Ihr Client selbst startet, oder als Remote-Streamable-HTTP-Bereitstellung, mit der sich beliebig viele Clients verbinden können.

Entwickelt auf Basis der Listmonk-OpenAPI-Spezifikation.

Quickstart

Lokal: Lassen Sie Ihren MCP-Client den Server selbst per stdio starten — nichts muss von Hand ausgeführt werden, kein Port muss geöffnet werden. Fügen Sie ihn zur Konfiguration Ihres Clients hinzu (hier gezeigt für Claude Code; siehe Verbinden Ihres MCP-Clients weiter unten für Cursor, VS Code, Claude Desktop, OpenCode, LM Studio und 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

Remote: Starten Sie den Server einmal; er ist dann über HTTP für beliebig viele Clients erreichbar:

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

Weitere Details zu beiden Modi, einschließlich Docker, finden Sie unter Server ausführen.

Related MCP server: listmonk-mcp-bridge

Verbinden Ihres MCP-Clients

Jeder der folgenden Clients unterstützt zwei Einrichtungsarten — wählen Sie eine:

• Lokal (stdio): Der Client startet npx @kieksme/listmonk-mcp --stdio selbst als Unterprozess und kommuniziert über dessen stdin/stdout per MCP. Kein Server, der laufen muss, kein Port, keine Erreichbarkeitsprobleme — das ist in der Regel die einfachere Standardwahl für einen einzelnen lokalen Client.

• Remote (HTTP): Sie betreiben den Server selbst (siehe Server ausführen) und der Client verbindet sich mit dessen URL. Erforderlich, wenn mehrere Clients eine Serverinstanz gemeinsam nutzen oder der Server nicht auf Ihrem Rechner läuft.

pnpm statt npx für die lokale/stdio-Einrichtung verwenden: Jedes lokale (stdio) Beispiel unten verwendet command: "npx" mit args: ["-y", "@kieksme/listmonk-mcp", "--stdio"]. Wenn Sie pnpm bevorzugen, tauschen Sie es gegen command: "pnpm" mit args: ["dlx", "@kieksme/listmonk-mcp", "--stdio"] aus — und lassen Sie das -y weg. -y ist npx' Flag für „Installationsbestätigung überspringen"; pnpm dlx zeigt eine solche Aufforderung von vornherein nicht an, akzeptiert -y also gar nicht und beendet sich sofort mit ERROR Unknown option: 'y' (was beim Client als generisches „Verbindung geschlossen" erscheint, da der Prozess stirbt, bevor er überhaupt MCP spricht). Derselbe Tausch gilt für jede CLI-Form unten, die mit npx -y beginnt — ersetzen Sie sie durch pnpm dlx (ohne -y).

Hinweis zur Erreichbarkeit für die Remote/HTTP-Einrichtung: Ein Client benötigt http://localhost:3000 nur, wenn er auf demselben Rechner wie der Server läuft. Claude Code, Cursor, VS Code, OpenCode und LM Studio sind allesamt lokale Tools, daher funktioniert localhost direkt. Claude Desktop ist eine lokale App und kann normalerweise ebenfalls auf localhost zugreifen. ChatGPT und Claude.ai (die Web-Apps) laufen in der Cloud und können Ihr localhost nicht erreichen — um diesen Server mit ihnen zu nutzen, müssten Sie ihn irgendwo bereitstellen, das aus dem Internet erreichbar ist (oder ihn tunneln, z. B. mit ngrok http 3000), und stattdessen diese öffentliche URL verwenden. Die Connectors von ChatGPT unterstützen nur HTTP, daher gibt es dort weiter unten keine lokale/stdio-Option.

Claude Code

Lokal (stdio), projektspezifisch über .mcp.json im Repository-Stammverzeichnis:

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

Oder über die 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

Remote (HTTP), sobald der Server läuft (siehe Server ausführen):

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

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

Wenn Sie auf dem Server MCP_SERVER_AUTH_TOKEN gesetzt haben, fügen Sie den Header hinzu: claude mcp add --transport http listmonk http://localhost:3000/mcp --header "Authorization: Bearer <token>".

Cursor

Installation mit einem Klick (lokal/stdio, mit Platzhalter-Zugangsdaten, die Sie anschließend in den MCP-Einstellungen von Cursor ausfüllen müssen):

Oder konfigurieren Sie es manuell — lokal (stdio) über .cursor/mcp.json im Repository-Stammverzeichnis (oder global in ~/.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"
      }
    }
  }
}

Remote (HTTP), sobald der Server läuft:

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

Wenn Sie auf dem Server MCP_SERVER_AUTH_TOKEN gesetzt haben, übergeben Sie ihn als Header:

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

Sie können beide Einrichtungsarten auch über Cursor-Einstellungen → MCP → Neuen MCP-Server hinzufügen ergänzen.

VS Code

Installation mit einem Klick (lokal/stdio, mit Platzhalter-Zugangsdaten, die Sie anschließend in den MCP-Einstellungen von VS Code ausfüllen müssen):

Oder konfigurieren Sie es manuell — lokal (stdio) über .vscode/mcp.json im Repository-Stammverzeichnis:

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

Remote (HTTP), sobald der Server läuft (type ist hier erforderlich, da es kein command gibt, aus dem es abgeleitet werden könnte):

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

Claude Desktop

Lokal (stdio), in 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"
      }
    }
  }
}

Remote (HTTP): Einstellungen → Connectors → Benutzerdefinierten Connector hinzufügen, und fügen Sie http://localhost:3000/mcp als URL ein (der Server muss bereits laufen). Wenn die Konfigurationsdatei Ihrer Claude-Desktop-Version Remote-Server direkt unterstützt, lautet der entsprechende Eintrag:

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

OpenCode

Lokal (stdio), in opencode.json (Projekt- oder globale Konfiguration):

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

Remote (HTTP), sobald der Server läuft:

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

Hinweis zu enabled: Dieses Flag ist der eigene clientseitige Schalter von OpenCode — es aktiviert/deaktiviert lediglich die gesamte Serververbindung für diesen Client und hat nichts damit zu tun, welche listmonk-Tools/-Kategorien verfügbar gemacht werden. Bei der Remote-Einrichtung (HTTP) können Sie, um einzuschränken, welche Tools dieser bestimmte Client sieht (ohne den Server neu zu starten oder LISTMONK_ENABLED_TOOLS anzufassen), den Abfrageparameter tools an die url selbst anhängen:

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

Bei der lokalen Einrichtung (stdio) setzen Sie stattdessen LISTMONK_ENABLED_TOOLS in environment — die vollständige Selektor-Syntax finden Sie unter Auswählen, welche Tools verfügbar sind.

LM Studio

Installation mit einem Klick (lokal/stdio, mit Platzhalter-Zugangsdaten, die Sie anschließend in den MCP-Einstellungen von LM Studio ausfüllen müssen):

Oder konfigurieren Sie es manuell über ~/.lmstudio/mcp.json (Registerkarte „Program" → „Install" → „mcp.json bearbeiten") — lokal (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"
      }
    }
  }
}

Remote (HTTP), sobald der Server läuft:

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

ChatGPT

Die Connectors von ChatGPT (Einstellungen → Connectors → Erstellen, verfügbar in kostenpflichtigen Tarifen, die MCP unterstützen) akzeptieren nur eine öffentlich erreichbare HTTP-URL — ChatGPT läuft in der Cloud und kann keinen lokalen stdio-Prozess starten, daher ist die Remote-Einrichtung die einzige Option. Stellen Sie den Server (siehe Docker) auf einem Host mit öffentlicher URL bereit oder tunneln Sie Ihre lokale Instanz (z. B. ngrok http 3000), und registrieren Sie dann https://<your-host>/mcp als Connector-URL. Wenn Sie MCP_SERVER_AUTH_TOKEN gesetzt haben, können Sie in der Connector-Einrichtung von ChatGPT zusammen mit der URL ein Bearer-Token angeben.

Features

• Vollständige API-Abdeckung: Abonnenten, Kampagnen, Listen, Vorlagen, Medien, Bounces, Import, Einstellungen, Wartung, transaktionale Nachrichten, öffentliches Abonnement, Logs, Admin sowie Dashboard-/Sonstige-Endpunkte.

• Selektives Tool-Laden — aktivieren Sie nur die Kategorien/Tools, die Sie tatsächlich benötigen, damit der Kontext des LLM nicht auf einmal mit allen 72 Tool-Definitionen überflutet wird.

• Zwei Transports, ein Paket: stdio für einen vom Client gestarteten lokalen Prozess, zustandsloses Streamable HTTP für eine Remote-Bereitstellung (kein Sitzungsstatus, einfach horizontal hinter einem Load Balancer skalierbar).

• Optionaler Bearer-Token-Schutz vor /mcp (nur HTTP-Transport — stdio hat keinen Netzwerk-Listener, der geschützt werden könnte).

Server ausführen

Lokal (stdio)

Normalerweise starten Sie das nicht von Hand — Ihr MCP-Client startet es gemäß der Konfiguration unter Verbinden Ihres MCP-Clients weiter oben. Um es manuell auszuführen (z. B. um es außerhalb eines Clients zu testen), übergeben Sie --stdio oder setzen Sie MCP_TRANSPORT=stdio:

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

Der Prozess spricht MCP-JSON-RPC auf stdout und protokolliert auf stderr — er beendet sich, wenn sein stdin geschlossen wird (d. h. wenn der übergeordnete Client die Verbindung trennt). LISTMONK_ENABLED_TOOLS wählt weiterhin aus, welche Tools registriert werden, aber in diesem Modus gibt es keine Überschreibung pro Anfrage: ein Client-Prozess, ein fester Tool-Satz für dessen Lebensdauer.

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

Der MCP-Endpunkt ist POST http://localhost:3000/mcp (streamable HTTP, zustandslos — keine Sitzungsaushandlung erforderlich).

Docker

Das veröffentlichte Image (ghcr.io/kieksme/mcp-listmonk:latest) unterstützt beide Transports — es ist derselbe Einstiegspunkt wie bei npx, daher gelten die obigen Flags auf dieselbe Weise.

Remote (HTTP) — Port veröffentlichen:

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

Lokal (stdio) — stdin angehängt lassen (-i) statt einen Port zu veröffentlichen; das ist das, was Sie hinter command/args eines Clients setzen würden (z. B. docker als Befehl), wenn Sie den Container lieber ausführen möchten, als npx das Paket holen zu lassen:

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

Konfiguration

Setzen Sie diese Umgebungsvariablen beim Starten des Servers:

Sicherheitshinweis: LISTMONK_API_USER/LISTMONK_API_TOKEN authentifizieren diesen Server gegenüber Listmonk, nicht MCP-Clients gegenüber diesem Server. Ohne MCP_SERVER_AUTH_TOKEN erhält jeder, der den Port erreichen kann, vollen Listmonk-Zugriff im Umfang des konfigurierten API-Benutzers. Erstellen Sie vorzugsweise einen API-Benutzer mit minimalen Rechten in Listmonk, der nur auf die Kategorien beschränkt ist, die Sie aktivieren möchten.

Auswahl der verfügbaren Tools

LISTMONK_ENABLED_TOOLS akzeptiert ein JSON-Array (oder eine kommagetrennte Zeichenkette), dessen Einträge (Groß-/Kleinschreibung wird ignoriert) entweder sind:

• ein Kategoriename: subscribers, campaigns, templates, lists, media, import, bounces, settings, maintenance, public, transactional, logs, admin, miscellaneous — aktiviert jedes Tool in dieser Kategorie, oder

• ein exakter Toolname: z. B. listmonk_get_subscriber — aktiviert nur genau dieses eine Tool.

# 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

Lassen Sie es ungesetzt (oder []), um alle 72 Tools verfügbar zu machen.

Pro-Anfrage-Überschreibung (nur Remote/HTTP): Eine einzelne bereitgestellte Instanz kann auch verschiedenen Clients ohne Neustart unterschiedliche Tool-Sets bereitstellen, über den Header X-Listmonk-Enabled-Tools oder die Query-String ?tools= bei der POST /mcp-Anfrage — gleiche Selektorsyntax wie oben. Dies überschreibt LISTMONK_ENABLED_TOOLS nur für diese eine Anfrage. Es gibt kein Äquivalent für den lokalen/stdio-Transport: Jeder stdio-Prozess wird pro Client frisch erzeugt. Setzen Sie stattdessen einfach LISTMONK_ENABLED_TOOLS in der eigenen env/environment-Konfiguration des jeweiligen Clients.

Da die Query-String nur ein Teil der URL ist, ist dies der einfachste Weg, einem bestimmten Client (z. B. einem Eintrag in einer opencode.json, .mcp.json oder .cursor/mcp.json) ein reduziertes Tool-Set zu geben, während andere Clients weiterhin denselben Server mit dem vollständigen (oder einem anderen) Set ansprechen — setzen Sie einfach die url dieses Clients auf http://localhost:3000/mcp?tools=subscribers,campaigns, anstatt serverweite Umgebungsvariablen hinzuzufügen oder eine zweite Instanz aufzusetzen. Clients, die benutzerdefinierte Header unterstützen, können stattdessen X-Listmonk-Enabled-Tools verwenden, wodurch die URL selbst sauber bleibt.

Tool-Katalog (72 Tools)

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

Hinweise zu einigen nicht offensichtlichen Tools

• Massen-/Query-Abonnentenoperationen (listmonk_delete_subscribers_by_query, listmonk_blocklist_subscribers_by_query, listmonk_manage_subscriber_lists_by_query) werden gegen einen Listmonk-SQL-Filterausdruck ausgeführt und wirken auf jeden passenden Abonnenten ohne Vorschauschritt. Rufen Sie zuerst immer listmonk_list_subscribers mit derselben query auf, um die Anzahl der Treffer zu prüfen.

• Kampagnen-Vorschau-/Inhalts-Tools sind absichtlich in vier verschiedene Tools aufgeteilt, weil Listmonk vier verschiedene Endpunkte dafür bereitstellt: listmonk_get_campaign_preview rendert die Kampagne im aktuell gespeicherten Zustand; listmonk_preview_campaign_draft und listmonk_preview_campaign_text rendern einen nicht gespeicherten Inhalt, ohne etwas zu persistieren; listmonk_convert_campaign_content führt eine Formatkonvertierung durch und persistiert sie (z. B. Markdown → HTML) — es ist trotz des ähnlichen Bereichs keine Vorschau.

• listmonk_send_campaign_test ruft zuerst den aktuell gespeicherten Zustand der Kampagne ab und überschreibt nur die Felder, die Sie explizit übergeben, um zu vermeiden, dass versehentlich Felder geleert werden, die Listmonks eigene API sonst stillschweigend mit leeren Werten überschreiben würde.

Mitwirken

Möchten Sie aus dem Quellcode bauen, die Testsuite ausführen oder den Release-Prozess verstehen? Siehe CONTRIBUTING.md.

Lizenz

MIT © kieksme GbR