lexware-mcp-server

MCP-Server für die Lexware Office API. Verwalten Sie Rechnungen, Kontakte, Artikel, Belege und mehr über das Model Context Protocol.

Inoffiziell — Community-Projekt. Nicht verbunden mit, empfohlen von oder unterstützt durch die Lexware GmbH oder die Haufe Group. „Lexware“ und „Lexware Office“ sind Marken der jeweiligen Inhaber; sie werden hier nur zur Identifizierung der API verwendet, die dieser Client anspricht (nominative faire Nutzung).

66 Tools in 20 Ressourcen-Domänen, mit 6 Einstiegspunkten, damit Sie den passenden Server für das Tool-Limit Ihres MCP-Clients auswählen können.

Installation

npm install -g @lazyants/lexware-mcp-server

Oder direkt ausführen:

npx @lazyants/lexware-mcp-server

Related MCP server: e-rechnung-mcp

Konfiguration

Das API-Token wird in dieser Reihenfolge ermittelt:

1. OS-Schlüsselbund (empfohlen — das Token wird nie im Klartext auf die Festplatte geschrieben)

2. Umgebungsvariable LEXWARE_API_TOKEN

Token im OS-Schlüsselbund speichern

Holen Sie Ihr Token aus den Lexware Office API-Einstellungen und speichern Sie es dann mit dem nativen Anmeldedaten-Manager Ihres Betriebssystems.

[!IMPORTANT] Die folgenden Befehle lesen das Token über eine interaktive Eingabeaufforderung, statt es als Argument zu übernehmen, sodass es nie in Ihrem Shell-Verlauf oder in der Prozessliste landet. Vermeiden Sie es, das Token direkt in die Befehlszeile einzufügen.

macOS

Wenn Sie den Wert nach -w weglassen, fordert security zur Eingabe des Tokens auf (mit Bestätigung):

security add-generic-password -s "lexware-mcp" -a "api-token" -w

Windows (PowerShell)

cmdkey kann das Token nur als Befehlszeilenargument entgegennehmen, wodurch es in der Prozessliste sichtbar wird. Lesen Sie es stattdessen über eine versteckte Eingabeaufforderung und schreiben Sie es direkt über CredWrite in den Windows-Anmeldedaten-Manager, sodass das Token nie in argv landet. Der Zielname der Anmeldedaten ist <account>.<service> — api-token.lexware-mcp für den Standarddienst — genau das, was der Server zurückliest:

$secure = Read-Host -AsSecureString "Lexware API token"
Add-Type -Namespace LexwareKeyring -Name Native -MemberDefinition @'
[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
public struct CREDENTIAL {
    public uint Flags;
    public uint Type;
    [MarshalAs(UnmanagedType.LPWStr)] public string TargetName;
    [MarshalAs(UnmanagedType.LPWStr)] public string Comment;
    public System.Runtime.InteropServices.ComTypes.FILETIME LastWritten;
    public uint CredentialBlobSize;
    public IntPtr CredentialBlob;
    public uint Persist;
    public uint AttributeCount;
    public IntPtr Attributes;
    [MarshalAs(UnmanagedType.LPWStr)] public string TargetAlias;
    [MarshalAs(UnmanagedType.LPWStr)] public string UserName;
}
[DllImport("advapi32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
public static extern bool CredWriteW(ref CREDENTIAL credential, uint flags);
'@
$blob = [Runtime.InteropServices.Marshal]::SecureStringToCoTaskMemUnicode($secure)
try {
    $cred = New-Object LexwareKeyring.Native+CREDENTIAL
    $cred.Type = 1                              # CRED_TYPE_GENERIC
    $cred.Persist = 2                           # CRED_PERSIST_LOCAL_MACHINE
    $cred.TargetName = 'api-token.lexware-mcp'  # "<account>.<service>"
    $cred.UserName = 'api-token'
    $cred.CredentialBlob = $blob
    $cred.CredentialBlobSize = $secure.Length * 2   # UTF-16 bytes, no terminator
    if (-not [LexwareKeyring.Native]::CredWriteW([ref]$cred, 0)) {
        throw "CredWrite failed (Win32 error $([Runtime.InteropServices.Marshal]::GetLastWin32Error()))"
    }
    Write-Host 'Stored Lexware API token in Windows Credential Manager.'
} finally {
    [Runtime.InteropServices.Marshal]::ZeroFreeCoTaskMemUnicode($blob)
    $secure.Dispose()
    Remove-Variable secure, blob
}

Sie verwenden einen benutzerdefinierten LEXWARE_KEYRING_SERVICE (z. B. acme)? Setzen Sie TargetName auf api-token.acme, damit es übereinstimmt — der Server sucht das Token unter <account>.<service>.

Linux

secret-tool store --label="Lexware Office API" service lexware-mcp username api-token
# (prompts for the token value)

Sobald das Token gespeichert ist, benötigen MCP-Konfigurationsdateien keinerlei Anmeldedaten — der Server liest das Token beim Start aus dem Schlüsselbund.

Stattdessen eine Umgebungsvariable verwenden

Wenn Sie den Schlüsselbund nicht verwenden möchten, setzen Sie LEXWARE_API_TOKEN in Ihrer Shell oder in der MCP-Client-Konfiguration:

export LEXWARE_API_TOKEN=your-token-here

Umgebungsvariablen

Optional können Sie den öffentlichen Schlüssel für die Webhook-Signatur überschreiben, der von lexware_verify_webhook_signature verwendet wird (standardmäßig von Lexware abgerufen und zwischengespeichert):

export LEXWARE_WEBHOOK_PUBLIC_KEY="$(cat lexware-webhook-public.pem)"

Einstiegspunkte

Verwenden Sie Split-Server, um die Kontextgröße zu reduzieren — wählen Sie nur die Splits, die Sie benötigen.

Claude Code

Fügen Sie dies zu ~/.claude/settings.json hinzu. Wenn Sie das Token im OS-Schlüsselbund unter dem Standard-Dienstnamen lexware-mcp gespeichert haben (empfohlen), wird kein env-Schlüssel benötigt:

{
  "mcpServers": {
    "lexware": {
      "command": "npx",
      "args": ["-y", "@lazyants/lexware-mcp-server"]
    }
  }
}

Wenn Sie den Ansatz mit der Umgebungsvariable bevorzugen:

{
  "mcpServers": {
    "lexware": {
      "command": "npx",
      "args": ["-y", "@lazyants/lexware-mcp-server"],
      "env": { "LEXWARE_API_TOKEN": "your-token-here" }
    }
  }
}

Split-Server

Verwenden Sie Split-Server, um die Kontextgröße zu reduzieren — wählen Sie nur die Einstiegspunkte, die Sie benötigen. Das Flag -p @lazyants/lexware-mcp-server teilt npx mit, aus welchem Paket der Befehl stammt; das letzte Argument (z. B. lexware-mcp-sales) ist die spezifische Einstiegspunkt-Binärdatei, die in diesem Paket definiert ist (siehe Einstiegspunkte):

{
  "mcpServers": {
    "lexware-sales": {
      "command": "npx",
      "args": ["-y", "-p", "@lazyants/lexware-mcp-server", "lexware-mcp-sales"]
    },
    "lexware-contacts": {
      "command": "npx",
      "args": ["-y", "-p", "@lazyants/lexware-mcp-server", "lexware-mcp-contacts"]
    }
  }
}

Beispiel für mehrere Konten (zwei Lexware-Unternehmen, Tokens unter separaten Schlüsselbund-Dienstnamen gespeichert):

{
  "mcpServers": {
    "lexware-company-a": {
      "command": "npx",
      "args": ["-y", "@lazyants/lexware-mcp-server"],
      "env": { "LEXWARE_KEYRING_SERVICE": "lexware-company-a" }
    },
    "lexware-company-b": {
      "command": "npx",
      "args": ["-y", "@lazyants/lexware-mcp-server"],
      "env": { "LEXWARE_KEYRING_SERVICE": "lexware-company-b" }
    }
  }
}

Claude Desktop

Fügen Sie dies zu claude_desktop_config.json hinzu. Mit dem OS-Schlüsselbund (empfohlen — setzt voraus, dass das Token unter dem Standard-Dienstnamen lexware-mcp gespeichert ist):

{
  "mcpServers": {
    "lexware": {
      "command": "npx",
      "args": ["-y", "@lazyants/lexware-mcp-server"]
    }
  }
}

Stattdessen mit einer Umgebungsvariable:

{
  "mcpServers": {
    "lexware": {
      "command": "npx",
      "args": ["-y", "@lazyants/lexware-mcp-server"],
      "env": { "LEXWARE_API_TOKEN": "your-token-here" }
    }
  }
}

Tools

Invoices (5 Tools) — Vertrieb

lexware_create_invoice (supports finalize=true at creation), lexware_get_invoice, lexware_download_invoice_file, lexware_pursue_invoice, lexware_deeplink_invoice

Credit Notes (5 Tools) — Vertrieb

lexware_create_credit_note, lexware_get_credit_note, lexware_download_credit_note_file, lexware_pursue_credit_note, lexware_deeplink_credit_note

Quotations (4 Tools) — Vertrieb

lexware_create_quotation, lexware_get_quotation, lexware_download_quotation_file, lexware_deeplink_quotation

Order Confirmations (5 Tools) — Vertrieb

lexware_create_order_confirmation, lexware_get_order_confirmation, lexware_download_order_confirmation_file, lexware_pursue_order_confirmation, lexware_deeplink_order_confirmation

Delivery Notes (5 Tools) — Vertrieb

lexware_create_delivery_note, lexware_get_delivery_note, lexware_download_delivery_note_file, lexware_pursue_delivery_note, lexware_deeplink_delivery_note

Down Payment Invoices (3 Tools) — Vertrieb

lexware_get_down_payment_invoice, lexware_download_down_payment_invoice_file, lexware_deeplink_down_payment_invoice

Dunnings (4 Tools) — Vertrieb

lexware_get_dunning, lexware_download_dunning_file, lexware_pursue_dunning, lexware_deeplink_dunning

Voucherlist (1 Tool) — Vertrieb, Buchhaltung

lexware_list_voucherlist

Standardmäßig ist dies eine einseitige Durchreichung der API-Antwort. Zwei Ergänzungen sind optional:

• fetchAllPages: true folgt der Paginierung, bis jede Seite abgerufen ist, begrenzt auf 100 Anfragen. Das Ergebnis fügt fetchedPages und truncated hinzu, wobei Letzteres einen Satz markiert, der durch die Begrenzung abgeschnitten wurde — API-Felder wie totalElements bleiben erhalten.

• contactName (SQL-artige %/_-Platzhalter, ohne Beachtung der Groß-/Kleinschreibung) und hasOpenAmount filtern nach dem Abruf clientseitig, und beide implizieren fetchAllPages. Sie werden hier statt auf lexware_list_vouchers angewendet, weil /voucherlist die Antwortform ist, die contactName und openAmount enthält.

page kann mit keiner der drei Optionen kombiniert werden — diese Modi lesen jede Seite, daher ist ein Start-Offset bedeutungslos. Verwenden Sie stattdessen size, um die Batch-Größe zu steuern. Die Kombination wird abgelehnt und nicht stillschweigend ignoriert, sodass niemand annehmen kann, ein Offset sei berücksichtigt worden, obwohl er es nicht wurde.

Contacts (5 Tools) — Kontakte

lexware_list_contacts, lexware_get_contact, lexware_create_contact, lexware_update_contact, lexware_deeplink_contact

Articles (5 Tools) — Kontakte

lexware_list_articles, lexware_get_article, lexware_create_article, lexware_update_article, lexware_delete_article

Vouchers (6 Tools) — Buchhaltung

lexware_list_vouchers, lexware_get_voucher, lexware_create_voucher, lexware_update_voucher, lexware_upload_voucher_file, lexware_deeplink_voucher

lexware_list_vouchers erfordert voucherNumber. GET /vouchers ist ein Lookup-Endpunkt und keine durchsuchbare Sammlung — die API antwortet ohne ihn mit 400 "voucherNumber parameter is required". Zum Durchsuchen oder Filtern von Belegen verwenden Sie lexware_list_voucherlist, den Sammlungs-Endpunkt, der auch die Zusammenfassungsfelder (contactName, openAmount) enthält, die /vouchers nicht hat.

lexware_get_voucher normalisiert voucherStatus in Kleinbuchstaben und wiederholt eine 404 dreimal (1 s / 2 s / 4 s), um die Indexierungsverzögerung nach einem Upload abzudecken; wenn der Beleg immer noch fehlt, gibt es { voucherId, status: "processing", message } zurück. Andere Fehler werden als Fehler gemeldet.

Payments (1 Tool) — Buchhaltung

lexware_get_payments

Countries (1 Tool) — Referenz

lexware_list_countries

Payment Conditions (1 Tool) — Referenz

lexware_list_payment_conditions

Posting Categories (1 Tool) — Referenz

lexware_list_posting_categories

Profile (1 Tool) — Referenz

lexware_get_profile

Print Layouts (1 Tool) — Referenz

lexware_list_print_layouts

Event Subscriptions (5 Tools) — System

lexware_create_event_subscription, lexware_list_event_subscriptions, lexware_get_event_subscription, lexware_delete_event_subscription, lexware_verify_webhook_signature

Files (4 Tools) — System

lexware_upload_file, lexware_download_file, lexware_get_file_status, lexware_deeplink_file

lexware_get_file_status ruft GET /files/{id}/status auf. Das bloße GET /files/{id} ist die Binär-Download-Route — mit Accept: application/json antwortet es weiterhin mit 200 und dem base64-kodierten Dateiinhalt, sodass es niemals Status-Metadaten liefern kann. Die Status-Route ist scope-basiert: API-Schlüssel ohne die erforderliche Berechtigung erhalten von Lexware access_denied statt eines Status.

Beide Upload-Tools (lexware_upload_file und lexware_upload_voucher_file) akzeptieren die Datei entweder als contentBase64 oder als filePath — einen absoluten Pfad, der vom MCP-Serverprozess gelesen werden kann. Bevorzugen Sie filePath für alles Größere: Base64 bläht die Nutzlast um etwa ein Drittel auf und muss durch das Kontextfenster des Modells reisen. Mit filePath wird fileName standardmäßig auf den Basisnamen der Datei gesetzt und contentType wird für .png, .jpg/.jpeg, .tiff/.tif und .xml automatisch erkannt, mit Rückfall auf application/pdf. Geben Sie genau eine der beiden Optionen an — die Angabe beider oder keiner ist ein Validierungsfehler.

Uploads sind auf 5 MB begrenzt. Bei filePath wird die Größe aus dem geöffneten Deskriptor vor dem Lesen der Datei ermittelt, sodass eine zu große Datei nur einen stat kostet statt eines vollständigen Ladens in den Speicher, und alles, was keine reguläre Datei ist, wird sofort abgelehnt (das Lesen von /dev/zero würde sonst nie zurückkehren). Die dekodierte Byte-Anzahl wird danach erneut geprüft, was auch contentBase64 abdeckt. Fehler enthalten einen file_too_large-Fehler mit der tatsächlichen und der maximalen Größe.

Recurring Templates (3 Tools) — System

lexware_list_recurring_templates, lexware_get_recurring_template, lexware_deeplink_recurring_template

Sicherheit

• Nutzen Sie den OS-Keyring, um Ihr API-Token vollständig aus Konfigurationsdateien und der Shell-Historie herauszuhalten (siehe Konfiguration)

• Committen Sie Ihr API-Token niemals in die Versionskontrolle

• Verwenden Sie Nur-Lese-Zugriff, wenn Sie nur Ressourcen auflisten/abrufen müssen

• Create-, Update- und Delete-Tools verändern echte Geschäftsdaten — Rechnungen, Kontakte und Buchhaltungsdatensätze in Ihrem Lexware-Konto

• Das Raten-Limit wird automatisch behandelt: Anfragen werden bei 429 mit exponentiellem Backoff wiederholt, einschließlich Datei-Uploads — der Multipart-Body wird bei jedem Wiederholungsversuch neu aufgebaut, sodass er sicher erneut abgespielt werden kann

Veröffentlichung (Releasing)

Releases werden über das GitHub-Release-Ereignis ausgeliefert. Ablauf für Maintainer:

1. Version in package.json, package-lock.json und server.json erhöhen (npm version <x.y.z> --no-git-tag-version aktualisiert die ersten beiden zusammen). npm run check-versions schlägt hart fehl, es sei denn, package.json#/version, server.json#/packages[0].version und beide package-lock.json-Versionfelder (Root und packages[""]) stimmen überein. server.json#/version wird lockerer geprüft: Es muss vorhanden sein, wird aber nur als Regressionsprüfung gegen packages[0].version verglichen — es darf legitimerweise voraus sein (Registry-Neuveröffentlichungen erhöhen nur dieses Feld), sodass ein auf der vorherigen Version zurückgelassener Wert mit einer WARN:-Zeile und ohne Fehler durchgeht. Bei einer normalen Veröffentlichung sollten sich beide zusammen bewegen, lesen Sie also die Ausgabe des Skripts, statt sich auf den Exit-Code zu verlassen. CHANGELOG.md wird überhaupt nicht geprüft.

2. CHANGELOG.md aktualisieren.

3. Committen und den Versionssprung vor der Release-Erstellung in main mergen. Erstellen Sie dann den Tag selbst, auf einem SHA, den Sie geprüft haben, und erst danach das Release daraus:

   V=X.Y.Z && PR=<release-pr-number> &&
     SHA="$(gh pr view "$PR" --json mergeCommit -q .mergeCommit.oid)" && test -n "$SHA" &&
     git fetch origin main && git merge-base --is-ancestor "$SHA" origin/main &&
     PKG="$(git show "$SHA:package.json")" &&
     test "$(printf '%s' "$PKG" | node -pe 'JSON.parse(require("fs").readFileSync(0,"utf8")).version')" = "$V" &&
     CL="$(git show "$SHA:CHANGELOG.md")" &&
     printf '%s\n' "$CL" | awk -v v="$V" 'index($0,"## ["v"]")==1{f=1;next} /^## \[/{f=0} /^\[[0-9]+\.[0-9]+\.[0-9]+\]:/{f=0} f' > "/tmp/notes-v$V.md" &&
     grep -q '[^[:space:]]' "/tmp/notes-v$V.md" &&
     git tag -a "v$V" "$SHA" -m "v$V" &&
     git push origin "v$V" &&
     gh release create "v$V" --verify-tag --notes-file "/tmp/notes-v$V.md"

   Der Fehler, den das verhindert: Ohne vorhandenen Tag platziert gh release create einen auf der Spitze des Standard-Branches. Wenn der Bump also noch auf einem Release-Branch liegt, wird der Commit des vorherigen Releases getaggt. Der Workflow veröffentlicht dann die Version, die er in der package.json dieses Commits findet, und Sie erhalten ein vX.Y.Z-GitHub-Release, das stillschweigend die alte Version neu veröffentlicht. Seit 5.2.0 weigert sich der Veröffentlichungs-Workflow selbst, fortzufahren, wenn GITHUB_REF_NAME nicht v<package.json-Version> ist (#103), sodass ein falsch getaggtes Release jetzt vor npm publish fehlschlägt, statt stillschweigend neu zu veröffentlichen. Diese Absicherung greift jedoch erst, wenn der Workflow bereits läuft — die obige Reihenfolge ist es, die verhindert, dass der falsche Commit überhaupt erst getaggt wird. Verwenden Sie sie also weiterhin, statt sich darauf zu verlassen, dass der Workflow den Fehler abfängt.

   Jedes Element ist tragend:

   • gh pr view … .mergeCommit.oid benennt den eigenen Squash-Commit des Release-PRs. Ersetzen Sie nicht durch git rev-parse origin/main — das ist lediglich das, was sich zum Zeitpunkt Ihrer Betrachtung auf main befindet, sodass ein unabhängiger Merge in der Zwischenzeit getaggt und ausgeliefert würde. gh beendet sich mit 0 und gibt nichts aus für einen nicht gemergten PR, daher das explizite test -n.

   • Die &&-Kette stoppt beim ersten Fehler, statt zum irreversiblen Schritt durchzufallen. Beide git show-Aufrufe werden einer Variablen zugewiesen statt direkt gepipet, damit ihr Exit-Status tatsächlich geprüft wird — eine Pipeline meldet nur den Status ihres letzten Befehls, sofern pipefail nicht gesetzt ist, was hier nicht vorausgesetzt wird.

   • git merge-base --is-ancestor beweist, dass der Commit tatsächlich von main aus erreichbar ist. Bloße Existenz reicht nicht — ein Commit kann lokal vorhanden sein, weil ein anderer Branch gefetcht wurde, und wenn seine Versionsdateien zufällig passen, würde er sonst alle übrigen Prüfungen passieren.

   • Der Versionstest liest package.json aus dem Ziel-Commit, nicht aus dem Arbeitsbaum, der die richtige Version anzeigen würde, während $SHA woanders hinzeigt.

   • Das awk hebt den Abschnitt dieser Version aus der CHANGELOG.md des Commits für --notes-file. Ohne das wäre der Release-Body das, was --notes-from-tag in der Annotation findet — in diesem Ablauf der Literal-String vX.Y.Z, was für jede Version eine dürftige Release-Notiz ist und für ein Major mit Breaking Change aktiv irreführend. Es stoppt an der nächsten ## [-Überschrift oder an der ersten Link-Referenz-Definition, weil der älteste Eintrag in der Datei keine Überschrift danach hat und sonst den gesamten Link-Referenz-Block verschlucken würde. grep -q statt test -s sichert das Ergebnis ab: Ein Abschnitt, der abgesehen von seiner Leerzeile leer ist, erzeugt trotzdem eine Ein-Byte-Datei, die test -s akzeptiert.

   • --verify-tag lässt gh abbrechen, statt einen Tag zu erfinden, falls der Push nicht angekommen ist — die Absicherung gegen das oben beschriebene Zurückfallen von gh auf die Spitze-des-Standard-Branches-Verhalten.

   Wenn gh release create fehlschlägt, nachdem der Tag bereits gepusht wurde, führen Sie nicht den gesamten Block erneut aus — er stoppt bei git tag, was korrekt ist. Führen Sie nur den letzten Befehl erneut aus.

4. Der Workflow Publish to npm + MCP Registry läuft automatisch: Er führt npm publish mit Provenance aus, pollt die Registry, bis das Tarball verfügbar ist, und pusht dann die passende server.json über mcp-publisher an die MCP Registry.

Der Workflow überspringt npm publish sauber, wenn die Version bereits auf npm ist (Cutover-Absicherung für teilweise manuell veröffentlichte Releases).

Publishing-Authentifizierung — npm Trusted Publishing (kein Token)

Das Publishing verwendet npm Trusted Publishing über OIDC — es gibt kein NPM_TOKEN-Secret. Die id-token: write-Berechtigung des Workflows wird zur Veröffentlichungszeit gegen ein kurzlebiges Einmal-Publishing-Token eingetauscht, unter Verwendung der Trusted-Publisher-Bindung, die für @lazyants/lexware-mcp-server in der npm-Web-UI konfiguriert ist. Die einzige erforderliche Einrichtung ist diese Trusted-Publisher-Bindung auf npm; in den Repository-Secrets muss nichts gespeichert werden.

Haftungsausschluss

Dies ist ein inoffizielles, unabhängiges Community-Projekt. Es ist weder mit der Lexware GmbH, der Haufe Group noch deren Tochtergesellschaften verbunden, von ihnen unterstützt oder gesponsert. Für offiziellen Lexware-Support wenden Sie sich direkt an Lexware — Probleme mit diesem MCP-Server sollten hier gemeldet werden, nicht an Lexware.

„Lexware" und „Lexware Office" sind Marken ihrer jeweiligen Inhaber und werden im Namen und in der Dokumentation dieses Projekts unter nominativer Fair-Use-Nutzung verwendet, ausschließlich zur Identifizierung der Drittanbieter-API, mit der dieser Client verbunden ist.

Create-, Update- und Delete-Operationen verändern echte Geschäftsdaten in Ihrem Lexware-Konto. Die Autoren stellen diese Software „wie besehen" bereit und übernehmen keine Verantwortung für unbeabsichtigte Änderungen, Datenverlust oder andere Schäden, die aus ihrer Nutzung entstehen. Testen Sie gegen ein Sandbox- oder nicht-kritisches Konto, bevor Sie Schreiboperationen gegen Produktionsdaten ausführen.

Lizenz

FSL-1.1-MIT — siehe LICENSE für die vollständigen Bedingungen.