pnlcs-mcp

Ein Model Context Protocol-Server für PNLCS, das Open-Source-Abrechnungspanel. Verbinde Claude Code, Claude Desktop, Cursor, VS Code oder einen beliebigen anderen MCP-Client mit deiner PNLCS-Installation und arbeite in einfacher Sprache mit ihr:

„Welche Rechnungen sind überfällig?“ — „Zeig mir die Dienste und Domains dieses Kunden.“ — „Gibt es heute als Betrug eingestufte Bestellungen?“ — „Öffne ein Ticket für ada@example.com wegen ihrer Domain-Verlängerung.“

Null Abhängigkeiten. Der Server ist ein kleiner Node-Prozess, der mit der PNLCS-Admin-API spricht, die du bereits hast. Auf der PNLCS-Seite wird nichts installiert.

• npm: pnlcs-mcp

• Erfordert: Node 18+ auf dem Rechner, auf dem dein KI-Client läuft

• Transport: stdio (wird von deinem Client gestartet — kein Port, nichts zu hosten)

1. API-Zugangsdaten in PNLCS erstellen

1. Melde dich im Admin-Bereich deiner PNLCS-Installation an.

2. Gehe zu Konfiguration → API-Zugangsdaten.

3. Klicke auf Erstellen, gib einen Namen wie mcp ein und kopiere die beiden Werte, die dir angezeigt werden:

   • Identifier — der Benutzername der Zugangsdaten

   • Secret — wird nur einmal angezeigt; bewahre es sicher auf

Dieses Paar ist alles, was der Server braucht, übergeben über drei Umgebungsvariablen:

Related MCP server: WHMCS MCP Server

2. Verbinde deinen Client

Claude Code (CLI)

Ein Befehl:

claude mcp add pnlcs \
  --env PNLCS_URL=https://billing.example.com \
  --env PNLCS_IDENTIFIER=your_identifier \
  --env PNLCS_SECRET=your_secret \
  -- npx -y pnlcs-mcp

Füge --env PNLCS_ALLOW_WRITES=1 hinzu, wenn du auch die Schreib-Tools möchtest. Verwende --scope project, um den Eintrag über .mcp.json mit deinem Team zu teilen (lege das Secret in deiner Shell-Umgebung ab, nicht in der eingecheckten Datei). Überprüfe es mit claude mcp list; entferne es mit claude mcp remove pnlcs.

Claude Desktop

Bearbeite claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "pnlcs": {
      "command": "npx",
      "args": ["-y", "pnlcs-mcp"],
      "env": {
        "PNLCS_URL": "https://billing.example.com",
        "PNLCS_IDENTIFIER": "your_identifier",
        "PNLCS_SECRET": "your_secret"
      }
    }
  }
}

Starte Claude Desktop neu; die Tools erscheinen unter dem Hammersymbol.

Cursor

Einstellungen → MCP → Neuen globalen MCP-Server hinzufügen oder erstelle .cursor/mcp.json in deinem Projekt (gleiche JSON-Struktur wie oben bei Claude Desktop).

VS Code (Copilot-Agentenmodus)

Erstelle .vscode/mcp.json:

{
  "servers": {
    "pnlcs": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "pnlcs-mcp"],
      "env": {
        "PNLCS_URL": "https://billing.example.com",
        "PNLCS_IDENTIFIER": "your_identifier",
        "PNLCS_SECRET": "your_secret"
      }
    }
  }
}

Alles andere (Windsurf, Cline, Zed, ...)

Jeder MCP-Client, der einen Stdio-Server starten kann, verwendet dieselben drei Teile: Befehl npx, Argumente ["-y", "pnlcs-mcp"] und die obigen Umgebungsvariablen. Aus einem git checkout funktioniert node mcp/server.js identisch.

3. Tools

Lese-Tools — immer verfügbar

Schreib-Tools — nur mit PNLCS_ALLOW_WRITES=1

Ohne das Flag sind die Schreib-Tools nicht nur versteckt — ein Aufruf wird abgelehnt, bevor irgendein HTTP stattfindet. Ein für Berichte eingerichteter Assistent kann nicht einmal einen Sperren-Button sehen. Gib einer Berichtsinstallation ein Nur-Lese-Leben, indem du das Flag einfach nicht setzt.

4. Sicherheitshinweise

• Das Secret reist nur zwischen dem Rechner, auf dem dein KI-Client läuft, und deiner PNLCS-Installation, über dieselbe HTTPS-API, die auch deine Admin-Oberflächen verwenden. Es wird niemals an den Modellanbieter gesendet; das Modell sieht Tool-Ergebnisse.

• Bevorzuge dedizierte API-Zugangsdaten für MCP, damit du sie allein widerrufen kannst.

• PNLCS begrenzt API-Zugangsdaten (300 Anfragen/Minute pro Zugangsdaten), sodass ein außer Kontrolle geratener Agent deine Installation nicht bombardieren kann.

• Lasse PNLCS_ALLOW_WRITES deaktiviert, es sei denn, du möchtest wirklich, dass der Assistent in deinen Büchern handelt, und lies, was er vorschlägt, bevor du Tool-Aufrufe genehmigst, die Dinge erstellen oder ändern.

5. Fehlerbehebung

6. Tests

npm test führt die Offline-Suite aus: Sie startet den echten Serverprozess, spricht das echte Protokoll mit ihm und prüft die HTTP-Form jedes Tools gegen einen lokalen Stub — plus das Schreib-Gate in beide Richtungen, Batch-Anfragen aus älteren Protokollrevisionen, Versionsaushandlung, Timeouts und das Abarbeiten offener Anfragen beim Herunterfahren.

node test/live.mjs führt jedes Tool gegen eine echte Installation aus — richte es auf eine Demo, niemals auf Produktionsdaten; es erstellt klar benannte Wegwerfdaten für die Schreib-Tools und gibt pro Tool eine PASS/FAIL-Zeile aus.

Entwicklung

Dieses Paket wird im PNLCS-Monorepo unter mcp/ entwickelt; dieses Repository ist sein eigenständiges Distributions-Spiegelbild und entspricht immer der auf npm veröffentlichten Version.