csv2zugferd MCP-Server: config.yml mit KI einrichten

Seit Version 1.3.0 stellt csv2zugferd mcp das Tool als MCP-Server (Model Context Protocol) über stdio bereit. Ein KI-Assistent in Claude Desktop, Claude Code oder VS Code liest damit den Kopf einer CSV-Datei, entwirft die config.yml, prüft sie im Probelauf gegen den echten Mapping-Code und speichert die geprüfte Konfiguration als Datei. Der Produktivlauf bleibt bei der CLI: lokal, deterministisch, ohne Modell und ohne Cloud-Upload durch csv2zugferd.

Der MCP-Server ist kein Rechnungsgenerator im Chat. Er erzeugt keine XML- oder PDF-Dateien für den Produktivbetrieb und ersetzt die CLI nicht. Er ist die werkzeuggestützte Fortsetzung der KI-Hilfe für config.yml: Statt Dokumentationslinks in einen Prompt zu kopieren, fragt das Modell die Konfigurationsreferenz direkt ab und prüft seinen Entwurf gegen den echten Code.

Voraussetzungen

#

• csv2zugferd ab Version 1.3.1 (Download) – als Windows-Exe oder als .NET-Tool-Paket csv2zugferd von NuGet (benötigt das .NET-10-SDK, startet über dnx)
• ein MCP-Client: Claude Desktop, Claude Code, VS Code oder ein anderer Client mit stdio-Transport
• eine CSV-Datei mit der Zielstruktur, für die Einrichtung möglichst mit anonymisierten Beispieldaten

Einrichtung

#

Der Client startet den Server selbst; es gibt keinen Port, keine Sitzung und keinen API-Key. Logs schreibt der Server nach csv2zugferd/logs im lokalen Anwendungsdatenordner (Windows %LOCALAPPDATA%, sonst ~/.local/share; änderbar über CSV2ZUGFERD_LOG_DIR), Warnungen zusätzlich nach stderr.

Claude Desktop

#

claude_desktop_config.json (Menü Einstellungen → Entwickler → Konfiguration bearbeiten):

{
  "mcpServers": {
    "csv2zugferd": {
      "command": "C:\\Tools\\csv2zugferd-win-x64.exe",
      "args": ["mcp"]
    }
  }
}

Mit dem NuGet-Paket statt der Exe:

{
  "mcpServers": {
    "csv2zugferd": {
      "command": "dnx",
      "args": ["csv2zugferd@1.3.1", "mcp"]
    }
  }
}

Das Paket csv2zugferd auf nuget.org ist dort als MCP-Server gekennzeichnet und in der Official MCP Registry unter dem Namen de.zugferd-tools/csv2zugferd eingetragen. Clients und Kataloge, die aus der Registry lesen, finden den Server unter diesem Namen; die Versionsangabe im dnx-Aufruf hält die Installation reproduzierbar.

Claude Code

#

claude mcp add csv2zugferd -- C:\Tools\csv2zugferd-win-x64.exe mcp

oder mit dem NuGet-Paket:

claude mcp add csv2zugferd -- dnx csv2zugferd@1.3.1 mcp

VS Code

#

.vscode/mcp.json im Arbeitsbereich:

{
  "servers": {
    "csv2zugferd": {
      "type": "stdio",
      "command": "C:\\Tools\\csv2zugferd-win-x64.exe",
      "args": ["mcp"]
    }
  }
}

Ablauf im Gespräch

#

1. CSV-Struktur erfassen. Das Modell ruft csv2zugferd_csv_header_get mit dem Pfad der CSV auf und erhält die Spaltennamen in Dateireihenfolge, die Zeilenzahl und auf Wunsch bis zu drei Beispielzeilen (sampleRows).
2. Mapping erarbeiten. csv2zugferd_config_schema_get liefert die vollständige Konfigurationsreferenz: jeden YAML-Schlüssel mit Beschreibung, Typ, Default, zulässigen Werten und Wirkung je Betriebsart. Mit section (z. B. mapping.lineItems) holt das Modell nur einen Teilbaum. Daraus entwirft es die config.yml.
3. Probelauf prüfen und korrigieren. csv2zugferd_config_get meldet unbekannte Schlüssel, unzulässige Werte, ignorierte Abschnitte und – mit csvPath – fehlende oder ungenutzte Spalten. csv2zugferd_invoice_get führt das echte Mapping aus und zeigt Rechnungsnummer, Typ, Summen, Steueraufschlüsselung und Warnungen mit Code und Pfad. Das Modell korrigiert die YAML, bis Summen und Warnungen stimmen.
4. YAML speichern. csv2zugferd_config_file_create schreibt die geprüfte Konfiguration als Datei (vorhandene Dateien nur mit overwrite: true) und gibt den passenden CLI-Befehl zurück.
5. Ersten CLI-Lauf ausführen. Der Befehl wird mit PDF-Vorlage und Ausgabeverzeichnis ausgeführt und erzeugt XML und PDF. Dafür braucht es weder ein Modell noch einen laufenden MCP-Server. Die Konfiguration gilt danach für alle Rechnungen derselben CSV-Struktur.

Ein typischer Einstieg im Chat:

Lies den Kopf der Datei C:\Daten\rechnungen.csv mit zwei Beispielzeilen, hole die
Konfigurationsreferenz und erarbeite eine config.yml fuer csv2zugferd. Pruefe sie mit
config_get und invoice_get, bis keine Warnungen mehr auftreten, und speichere sie unter
C:\Daten\config.yml.

Werkzeuge

#

Zusätzlich stellt der Server drei Ressourcen bereit: die README als Konfigurationsreferenz und zwei Beispielkonfigurationen (rows und columns). Maßgeblich für das Modell ist csv2zugferd_config_schema_get, weil Clients Ressourcen nicht von sich aus lesen.

Prüfergebnisse und Antwortoptionen

#

• Warnungen sind Objekte mit stabilem englischem Code, vollständigem Konfigurationspfad und deutschem Text, zum Beispiel invalid_date an mapping.invoice.invoiceDate, config_field_ignored an mapping.lineItems.columnPattern oder invalid_iban_checksum an mapping.paymentMeans.sellerAccounts[0].iban. Das Modell kann die Stelle in der YAML damit direkt korrigieren.
• Rückfälle werden sichtbar: Ein unbekanntes Profil fällt auf Extended zurück, eine unbekannte Währung auf EUR, ein unbekannter lineItems.mode auf rows. csv2zugferd_config_get listet solche Werte unter invalidValues mit den zulässigen Werten und dem Rückfall; ein unbekannter Rechnungstyp oder Zahlungsart-Code ist dagegen ein Fehler.
• Fehler kommen als Tool-Ergebnis mit Code in der ersten Zeile, zum Beispiel csv_file_not_found, config_invalid_yaml (mit Zeile und Spalte) oder file_exists.
• Antwortumfang: Die Standardantwort des Probelaufs enthält Rechnungsnummer, Typ, Zähler, Summen, Steuergruppen und Warnungen, aber keine Positionen oder Parteien. includeLineItems und includeParties ergänzen sie gezielt; sampleRows steuert die Beispielzeilen des CSV-Kopfs. Lesende Werkzeuge liefern keine Antwort über 900 000 Byte.

Produktivlauf

#

Nach der Einrichtung läuft die Verarbeitung wie bisher lokal per CLI, ohne KI und ohne Cloud-Upload durch csv2zugferd:

.\csv2zugferd-win-x64.exe --csv .\rechnungen.csv --pdf .\vorlage.pdf --config .\config.yml --output .\output

Die gespeicherte config.yml ist wiederverwendbar: Jede weitere CSV mit derselben Struktur wird mit demselben Befehl verarbeitet, zum Beispiel in der Batch-Verarbeitung. Die erzeugten XML- und PDF-Dateien müssen vor produktiver Nutzung fachlich und technisch geprüft werden (Validierung).

Weiterführend

#

• YAML-Konfiguration – Aufbau der config.yml
• CSV-Modi – rows, columns-suffix, columns-prefix
• KI-Hilfe für config.yml – Prompt-Vorlagen ohne MCP
• CLI-Parameter – der Produktivlauf
• NuGet-Paket csv2zugferd – .NET-Tool-Paket mit MCP-Server-Manifest
• Official MCP Registry – Eintrag de.zugferd-tools/csv2zugferd
• GitHub-Release – Windows-Exe, NuGet-Paket und Prüfsummen