lxw-cli 0.4.0

Inoffizielles CLI/TUI/MCP-Tool für die Lexware Office API (vormals lexoffice)

lxw-cli

Ein Kommandozeilen-Tool für die Lexware Office API (vormals lexoffice). Liest Rechnungen, Kontakte, Belege, Artikel, Angebote, Aufträge und Lieferscheine — und legt Drafts neu an.

Hinweis: Inoffizielles Community-Tool — kein Produkt der Haufe-Lexware GmbH & Co. KG und nicht mit ihr verbunden. „Lexware" ist eine Marke der Haufe Group.

Features

• Zwei Frontends auf einem UI-freien Core: CLI (skriptbar) und interaktive TUI (lxw ohne Argumente)
• Lesen: list (paginiert + Filter), get (Detail), pdf (Download)
• Schreiben: create-draft für Belege (Rechnungen, Angebote, Aufträge, Lieferscheine, Belege), create für Stammdaten (Kontakte, Artikel)
• Paginierung: --limit N, --all/-a bzw. --limit 0 für alle Treffer über alle Seiten
• Artikel-Volltextsuche: articles list --search/-q (Bezeichnung, Beschreibung, Teil-Artikelnummer)
• Kontakte: --customer / --vendor (nur Kunden/Lieferanten), optional --grouped
• Ausgabe: Tabelle (Rich), JSON (pipe-fähig), CSV, Datei-Output
• PDF-Download nach Datei oder Verzeichnis (Auto-Dateiname); -o optional
• Komfort: API-Key-Abfrage beim ersten Start, Warte-Animation bei längeren Abrufen
• Eingebauter Rate-Limit-Schutz (2 req/s) + automatische Retries auf 429/5xx

Installation

Läuft auf macOS, Linux und Windows (Python ≥ 3.11). Empfohlen als isoliertes Tool mit uv oder pipx:

uv tool install lxw-cli      # oder: pipx install lxw-cli
lxw profile

Alternativ klassisch in ein Environment:

pip install lxw-cli

Windows (cmd, ohne Vorinstallation)

Für ein frisches Windows 11 ohne uv und ohne Python — die vier Zeilen laufen per Copy-Paste in cmd.exe durch (volle Pfade, damit kein Terminal-Neustart nötig ist; uv lädt sich ein passendes Python selbst):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
"%USERPROFILE%\.local\bin\uv.exe" tool install lxw-cli
"%USERPROFILE%\.local\bin\uv.exe" tool update-shell
"%USERPROFILE%\.local\bin\lxw.exe" profile

Ab dem nächsten cmd-Fenster reicht dann überall einfach lxw. Der API-Key wird beim ersten Start abgefragt und unter %APPDATA%\lexware\.env gespeichert.

Update

Auf die neueste Version von PyPI:

uv tool upgrade lxw-cli        # oder: pipx upgrade lxw-cli
lxw --version                  # Kontrolle

Sieht uv eine frisch veröffentlichte Version noch nicht (das PyPI-CDN braucht nach einem Release ein paar Minuten) oder ist das Tool auf eine exakte Version gepinnt, hilft ein Neu-Install auf latest:

uv tool install --force lxw-cli@latest

Der MCP-Server für Claude nutzt das Update automatisch mit — bereits laufende Claude-Sessions müssen dafür einmal neu gestartet werden.

Aus dem Quellcode (Entwicklung)

git clone https://github.com/OEM-Mrks/lxw-cli
cd lxw-cli
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"

Lokalen Arbeitsstand ohne Release als globales lxw installieren:

uv tool install --force --reinstall .

(--reinstall ist nötig — bei unveränderter Versionsnummer nimmt uv sonst den gecachten Build.)

API-Key konfigurieren

Lege einen API-Key in deinem Lexware-Account an: https://app.lexware.de/addons/public-api

Einfachste Variante: Ruf lxw einfach auf. Findet das Tool keinen Key, fragt es im Terminal danach, prüft ihn gegen die API und speichert ihn unter ~/.config/lexware/.env (Datei-Rechte 0600, nur für dich lesbar; unter Windows %APPDATA%\lexware\.env). Ab dann funktioniert lxw aus jedem Verzeichnis, ohne weitere Einrichtung.

lxw profile
# → Kein Lexware API-Key gefunden. Lexware API-Key: ********
# → ✓ API-Key gespeichert in ~/.config/lexware/.env — angemeldet als Acme GmbH

Der Key wird in dieser Reihenfolge gesucht:

1. gesetzte Environment-Variable LEXWARE_API_KEY
2. projektlokale .env (vom aktuellen Verzeichnis aufwärts — praktisch für die Entwicklung)
3. globale ~/.config/lexware/.env (bzw. $XDG_CONFIG_HOME/lexware/.env; unter Windows %APPDATA%\lexware\.env)

Wer es manuell vorziehen will, kann den Key auch direkt setzen:

cp .env.example .env   # projektlokal
# LEXWARE_API_KEY=… eintragen

In nicht-interaktiven Kontexten (Pipes, Cron, MCP-Server über stdio) wird nicht gefragt — dort muss der Key vorab über eine der drei Quellen vorhanden sein.

Quickstart

# Auth-Test: zeigt Firmenprofil
lxw profile

# Rechnungen (Tabelle) — Standard: 25 Einträge
lxw invoices list --limit 10

# ALLE Rechnungen laden (paginiert automatisch über alle Seiten)
lxw invoices list --all
lxw invoices list --limit 0          # gleichbedeutend

# Archivierte sind standardmäßig ausgeblendet — bei Bedarf einblenden
lxw invoices list --include-archived
lxw contacts list --include-archived

# Rechnungen als JSON in jq pipen
lxw --json invoices list --status open | jq '.[].voucherNumber'

# CSV-Export von Kunden
lxw --csv --output kunden.csv contacts list --customer --limit 200

# Artikel suchen — Teiltreffer in Bezeichnung, Beschreibung und Artikelnummer
lxw articles list --search "schraube"
lxw articles list -q "SCH-"          # auch Teil-Artikelnummern
lxw articles list --number SCH-001   # exakte Artikelnummer (serverseitig, schnell)

# Rechnung per Belegnummer abrufen (UUID auch möglich)
lxw invoices get FB2600682
lxw --json invoices get FB2600682 | jq '.totalGrossAmount'

# PDF einer Rechnung herunterladen (UUID oder Belegnummer)
lxw invoices pdf FB2600682                       # → ./invoice-FB2600682.pdf
lxw invoices pdf FB2600682 --output ~/Rechnungen # Verzeichnis: Dateiname automatisch
lxw invoices pdf FB2600682 --output rechnung.pdf # exakter Dateipfad

# Kontakt anlegen (Stammdaten — kein Draft)
lxw contacts create --body '{
  "roles": {"customer": {}},
  "company": {"name": "Test GmbH"}
}'

# Komplexere Bodies aus Datei
lxw invoices create-draft --body @invoice-template.json

Verfügbare Befehle

Befehl	Zweck
lxw profile	Firmenprofil abrufen (Auth-Test)
lxw invoices	Rechnungen: list, get, pdf, create-draft
lxw contacts	Kontakte: list, get, create
lxw vouchers	Belege: list, get, create-draft
lxw articles	Artikel: list, get, create (mit Volltextsuche)
lxw quotations	Angebote: list, get, pdf, create-draft
lxw orders	Aufträge (Auftragsbestätigungen): list, get, pdf, create-draft
lxw delivery-notes	Lieferscheine: list, get, pdf, create-draft

Hinweis: create-draft legt Belege als Entwurf an (Draft, nicht finalisiert); Stammdaten (Kontakte, Artikel) kennen keinen Draft-Status und werden mit create direkt angelegt.

Detail-Hilfe mit lxw <command> --help bzw. lxw <command> list --help.

Suchen, Filtern & Paginierung

Alle list-Befehle teilen sich dasselbe Paginierungs-Verhalten und besitzen befehlsspezifische Filter. Intern wird serverseitig seitenweise abgerufen — immer mit dem API-Maximum von 250 Datensätzen/Request (mit Rate-Limit-Schutz), damit so wenige Requests wie möglich nötig sind.

Menge: --limit und --all (für jeden list-Befehl)

Option	Wirkung
--limit N, -n N	Maximal N Einträge (Standard: 25).
--limit 0	Unbegrenzt — lädt alle Treffer über alle Seiten.
--all, -a	Wie --limit 0; überschreibt ein gesetztes --limit.

lxw invoices list --all          # alle Rechnungen
lxw contacts list --customer -a  # alle Kunden

Am Listenende wird die Gesamtzahl der Datensätze ausgegeben (aus dem totalElements der API) — z.B. → 25 von 1234 Rechnungen angezeigt (mehr mit --all) bzw. → 1234 Kontakte gesamt, wenn alles geladen wurde. Diese Zeile geht auf stderr, stört also --json/--csv-Pipes nicht. Bei der clientseitigen Artikelsuche wird stattdessen die Trefferzahl gezeigt (→ 12 Treffer).

Befehlsspezifische Filter

Befehl	Filter-Optionen
invoices list	--status, --number (exakt), --contact-id, --include-archived
vouchers list	--type, --status, --number (exakt), --contact-id, --include-archived
contacts list	--name (≥3 Z.), --email (≥3 Z.), --number, --customer, --vendor, --grouped/--flat, --include-archived
articles list	--search/-q (Volltext), --number (exakt), --type product|service, --gtin (exakt)
quotations list	--status, --include-archived
orders list	--status, --include-archived
delivery-notes list	--status, --include-archived

--status und --type sind komma-separiert (z.B. --status open,paid).

Archivierte ausblenden (Standard)

Archivierte Datensätze werden bei Belegen (Rechnungen, Belege, Angebote, Lieferscheine) und Kontakten standardmäßig ausgeblendet — --include-archived zeigt sie. Bei Belegen filtert die API serverseitig (archived=false), die Gesamtzahl bleibt also exakt; bei Kontakten geschieht es clientseitig (siehe unten). Der Footer weist mit · ohne archivierte (--include-archived zeigt alle) darauf hin.

Kontakte: nur Kunden oder nur Lieferanten

contacts list liefert standardmäßig eine zusammenhängende Liste (nicht getrennt — gut für Pipes und Weiterverarbeitung durch LLMs). Auf Wunsch nur eine Rolle oder optional gruppiert:

lxw contacts list                    # aktive Kontakte, eine Liste
lxw contacts list --customer         # nur Kunden (serverseitig gefiltert)
lxw contacts list --vendor           # nur Lieferanten (serverseitig gefiltert)
lxw contacts list --grouped          # Tabelle in Kunden-/Lieferanten-Abschnitte
lxw contacts list --include-archived # archivierte Kontakte einblenden

Bei --grouped zeigt jede Tabelle die passende Kunden- bzw. Lieferantennummer; Kontakte mit beiden Rollen erscheinen in beiden Abschnitten (role-Spalte = customer+vendor). --json und --csv sind immer eine flache Liste mit role-Spalte.

Archivierte Kontakte werden standardmäßig ausgeblendet — --include-archived zeigt sie wieder. Da die Kontakt-API archivierte nicht serverseitig filtern kann, geschieht das clientseitig: lxw blättert durch die Seiten und überspringt archivierte, bis genug aktive für das --limit zusammen sind. Der Footer zeigt dann z.B. → 298 aktive Kontakte gesamt (14 archivierte ausgeblendet).

Artikel-Volltextsuche: --search / -q

Die Lexware-API filtert Artikel serverseitig nur exakt (--number, --gtin, --type). Für unscharfe Suche nach Bezeichnung, Beschreibung oder Teil-Artikelnummer gibt es --search/-q — dabei werden Artikel clientseitig durchsucht (Teiltreffer, Groß-/Kleinschreibung egal):

lxw articles list -q "schraube"        # Bezeichnung/Beschreibung
lxw articles list -q "SCH-"            # Teil-Artikelnummer
lxw articles list --number SCH-001     # exakte Nummer (serverseitig, schnell)
lxw articles list -q "kabel" --type product --all   # kombinierbar

Hinweis: --search scannt im Zweifel alle Artikel (bricht ab, sobald genug Treffer für --limit gefunden sind). Bei sehr großen Beständen entsprechend langsamer als die exakten Server-Filter.

Globale Optionen

Flag	Zweck
--json	JSON-Ausgabe (für Pipelines)
--csv	CSV-Ausgabe
--output PATH, -o	In Datei statt stdout schreiben
--version, -V	Version anzeigen

Interaktive TUI

Neben der CLI gibt es eine Terminal-UI zum Durchstöbern deiner Daten (Rechnungen, Kontakte, Belege, Artikel, Angebote, Aufträge, Lieferscheine) — und zum Anlegen neuer Aufträge als Entwurf.

lxw            # ohne Argumente im Terminal → TUI startet automatisch
lxw-tui        # oder explizit

• Links die Entitäten wählen (Pfeile + Enter), rechts die Liste; Enter auf einer Zeile öffnet die Detailansicht, Esc schließt sie.
• Die Detailansicht zeigt die Felder menschenlesbar (deutsche Feldnamen, Datumsangaben als TT.MM.JJJJ, ja/nein, verschachtelte Strukturen als Pfad wie Adressen › Rechnungsadresse › Ort). Mit j wechselt man jederzeit auf das rohe JSON der API und zurück.
• Tastenkürzel: Tab Fokus wechseln · r aktualisieren · n neuer Auftrag · m mehr laden · / suchen · q beenden (immer als Leiste unten sichtbar).
• Paginierung: Jede Liste lädt zunächst eine volle API-Seite (250 Datensätze — das Server-Maximum pro Request). Scrollt man auf die letzte Zeile (oder drückt m), wird automatisch der nächste Schwung nachgeladen; die Cursor-Position bleibt erhalten. Die Statuszeile zeigt den Stand, z.B. 250 von 1234 Rechnungen — ans Ende scrollen oder m lädt mehr.
• Suchen (/): öffnet eine Suchleiste über der Tabelle. Tippen filtert sofort die bereits geladenen Zeilen (clientseitig, über alle sichtbaren Spalten). Enter sucht über die API — bei Kontakten per Name bzw. E-Mail (enthält die Eingabe ein @, wird die E-Mail-Suche verwendet; min. 3 Zeichen), bei Artikeln per Volltextsuche. In den API-Treffern kann anschließend weiter lokal gefiltert werden. Esc schließt die Suche und stellt die normale Liste wieder her.
• Auftrag anlegen (n): Kunde per Namenssuche wählen, Artikel suchen und mit Menge und (editierbarem) Netto-Einzelpreis als Positionen hinzufügen — der Preis wird aus dem Artikel vorbelegt und kann vor dem Hinzufügen überschrieben werden. Optional Einleitungs- und Schlusstext eintragen, dann „Auftrag anlegen" — der Auftrag wird als Entwurf gespeichert und die Auftragsliste geöffnet. Während Suchen und Anlegen laufen, zeigt das Formular eine Lade-Animation. Finalisieren/Versenden bleibt bewusst der Lexware-UI vorbehalten.
• Firmenname oben = Verbindungstest; Fehler aus der API werden als Hinweis und in der Statuszeile angezeigt (nie verschluckt).

Die TUI startet nur im interaktiven Terminal. Sobald lxw mit Argumenten aufgerufen wird oder die Ausgabe in eine Pipe/Datei geht, verhält es sich unverändert wie die CLI — Skripte und … | jq bleiben also unberührt.

Technisch spricht die TUI ausschließlich den UI-freien Core (lxw_cli.core) — exakt dieselbe API wie CLI und MCP-Server.

Claude-Integration (MCP-Server)

Das CLI bringt einen eingebauten MCP-Server mit, mit dem Claude Code, Claude Desktop und Cowork deine Lexware-Daten direkt abfragen können.

Setup in einem Schritt

lxw mcp install-claude    # Claude Code
lxw mcp install-desktop   # Claude Desktop + Cowork

Die beiden Frontends haben getrennte Konfigurationen: install-claude registriert den Server bei Claude Code (via claude mcp add, Scope user), install-desktop trägt ihn in die claude_desktop_config.json von Claude Desktop ein — das deckt auch Cowork ab. Wichtig: install-desktop bei beendetem Claude Desktop ausführen (Quit, nicht nur Fenster schließen) — die laufende App schreibt ihre Konfiguration aus dem Arbeitsspeicher zurück und überschreibt externe Änderungen. Danach Desktop starten.

Der API-Key wird dabei nicht an Claude übergeben — der Server liest ihn selbst aus ~/.config/lexware/.env (chmod 600; Windows: %APPDATA%\lexware\.env); falls er dort noch fehlt, legen die Install-Befehle ihn einmalig ab. Prüfen:

lxw mcp status    # zeigt Registrierung für Claude Code und Desktop
claude mcp list   # 'lexware' muss in der Liste erscheinen (Claude Code)

Öffne Claude Code in einem Projekt und frag z.B.:

"Wie viele offene Rechnungen habe ich?" "Lade die PDF von Rechnung FB2600682 herunter." "Zeig mir alle Kunden, deren Name mit 'A' anfängt."

Claude erkennt die Tools automatisch und ruft sie auf.

Verfügbare MCP-Tools

31 Tools mit identischem Verhalten wie die CLI-Befehle:

• Info: version (meldet die laufende Version + Build-Zeitstempel — nützlich, wenn eine Client-UI wie ChatGPT eine gecachte/alte Version anzeigt)

• Belegkette (weiterführen): continue_document führt einen Beleg in den Folgebeleg fort und hält beide verknüpft (precedingSalesVoucherId). Der Quelltyp wird automatisch erkannt (Belegnummer oder id). Unterstützte Wege (wie in Lexware):

  • Angebot → Auftrag · Lieferschein · Rechnung
  • Auftrag → Lieferschein · Rechnung
  • Lieferschein → Rechnung
  • Rechnung → Lieferschein · Rechnungskorrektur

  Inhalte (Kunde, Positionen, Texte) werden übernommen, der Folgebeleg entsteht als Entwurf. Für Rechnung/Rechnungskorrektur muss der Ausgangsbeleg festgeschrieben sein (sonst klare Meldung statt HTTP 406). Abschlagsrechnung und Serienrechnung sind über die Lexware-API nicht erstellbar — das meldet das Tool klar.

• Lesen: profile, list_invoices, get_invoice, download_invoice_pdf, list_contacts, get_contact, list_vouchers, get_voucher, list_articles, get_article, list_quotations, get_quotation, download_quotation_pdf, list_order_confirmations, get_order_confirmation, download_order_confirmation_pdf, list_delivery_notes, get_delivery_note, download_delivery_note_pdf

• Belege als Draft anlegen: create_invoice_draft, create_voucher_draft, create_quotation_draft, create_order_confirmation_draft, create_delivery_note_draft

• Stammdaten anlegen (kein Draft): create_contact, create_article

• Stammdaten bearbeiten (Teil-Update mit Auto-Merge + automatischem version-Handling): update_contact, update_article. Es werden nur die übergebenen Felder geändert; verschachtelte Objekte werden feldweise zusammengeführt, Listen komplett ersetzt. (Kontakt-archived ist in der Lexware-API read-only und kann nicht per API gesetzt werden. Firmen-Kontakte mit mehr als einem Ansprechpartner lassen sich per Lexware-API grundsätzlich nicht aktualisieren — update_contact meldet das klar, statt eines rohen HTTP 406.)

• Funktionswunsch melden: request_feature erstellt einen unverbindlichen Feature-Wunsch als fertigen Text (subject/body) samt Anbieter-Adresse (to = [e-mail]). Der Server versendet nichts — der Nutzer kopiert den Text und schickt ihn selbst per E-Mail. Dies ist ein Endkundenprodukt: der Assistent baut keine Funktionen selbst, sondern bietet bei fehlenden Funktionen nur diesen Weg an.

Alle document-Tools (get_*, download_*_pdf) akzeptieren UUID oder Belegnummer (z.B. FB2600682). PDFs landen in ~/Downloads/lexware/.

Die list_*-Tools bieten dieselben Optionen wie die CLI:

• limit begrenzt die Trefferzahl; limit=0 lädt alle (paginiert intern).
• list_articles hat search für die Volltextsuche (Bezeichnung/Beschreibung/Teil-Artikelnummer) zusätzlich zum exakten article_number.
• list_contacts filtert mit customer / vendor nach Rolle.
• Belege-Tools (list_invoices, list_vouchers, list_quotations, list_delivery_notes) und list_contacts blenden archivierte standardmäßig aus; include_archived=true zeigt sie.

Weitere mcp-Befehle

lxw mcp status                    # zeigt Registrierung (Claude Code + Desktop)
lxw mcp install-claude --force    # Re-Install Claude Code (z.B. nach Pfad-Wechsel)
lxw mcp install-desktop --force   # Re-Install Claude Desktop/Cowork
lxw mcp uninstall-claude          # aus Claude Code entfernen
lxw mcp uninstall-desktop         # aus Claude Desktop entfernen
lxw mcp serve                     # läuft direkt — wird von Claude intern aufgerufen

Multi-User-Server (HTTP) — ein Server, jeder mit eigenem Key

Neben dem lokalen stdio-Modus gibt es lxw-mcp-http: einen zentralen MCP-Server für mehrere Nutzer, bei dem jeder seinen eigenen Lexware-API-Key mitbringt. Der Server speichert keine Keys — er ist ein zustandsloser Proxy.

LXW_MCP_PUBLIC_URL=https://mcp.example.com \
LXW_MCP_SECRET='ein-langes-zufaelliges-secret' \
lxw-mcp-http    # lauscht auf 127.0.0.1:8788 (LXW_MCP_HOST/LXW_MCP_PORT)

Zwei Wege, den eigenen Key mitzubringen:

1. Direkt als Bearer-Header (Claude Code, Cursor, Skripte — alles, was eigene Header kann). Der Key bleibt in der lokalen Client-Config:

   claude mcp add lexware --transport http https://mcp.example.com/mcp \
     --header "Authorization: Bearer ${LEXWARE_API_KEY}"
   

2. OAuth (claude.ai, ChatGPT — Clients ohne Header-Support): Beim Verbinden öffnet sich eine Consent-Seite des Servers, auf der man einmalig seinen Lexware-Key eingibt. Der Server prüft ihn gegen die Lexware-API und stellt ein Zugriffstoken aus, in dem der Key verschlüsselt eingebettet ist (Fernet, LXW_MCP_SECRET). Das Token liegt beim Client auf dem Gerät des Nutzers; der Server entschlüsselt es nur pro Request und persistiert ausschließlich die OAuth-Client-Registrierungen (LXW_MCP_DATA_DIR, Standard ~/.config/lexware/mcp/).

Hinweise für den Betrieb:

• LXW_MCP_SECRET fest setzen — ohne festes Secret werden alle Tokens bei jedem Neustart ungültig. Rotieren des Secrets invalidiert bewusst alle ausgestellten Tokens.
• Vor den Server gehört ein HTTPS-Reverse-Proxy (Caddy, nginx, Cloudflare Tunnel, tailscale serve, …); LXW_MCP_PUBLIC_URL ist die von außen sichtbare Basis-URL (sie steht in den OAuth-Metadaten).
• PDF-Downloads liefern über HTTP das PDF als Binärinhalt zurück (statt eines Pfads auf der Server-Platte wie im stdio-Modus).
• Tokens laufen nach 24 h ab; Clients erneuern sie automatisch per Refresh-Token. Ein geleaktes Token wird wirkungslos, sobald der zugehörige Lexware-Key unter https://app.lexware.de/addons/public-api widerrufen wird.

request_feature braucht keine Konfiguration: es liefert nur einen fertigen Text + die Empfänger-Adresse ([e-mail]) zurück, den der Nutzer selbst per E-Mail sendet. Der Server verschickt nichts.

Out of Scope (v1)

Bewusst nicht enthalten:

• Finalisierung von Rechnungen (/finalize)
• Stornierungen / Credit Notes als eigene Workflows
• Webhooks / Event-Subscriptions
• Multi-Account-Profile (nutze stattdessen verschiedene .env-Dateien)

Entwicklung

uv pip install -e ".[dev]"
pytest -v
ruff check src tests

Lizenz

MIT