nkfix-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| NKF_URL | Yes | Adresse der Instanz, z. B. http://127.0.0.1:6060 oder https://nkf.example.org (Pflicht) | |
| NKF_API_KEY | No | Zugriffsschlüssel nkf_… (empfohlen) | |
| NKF_PASSWORD | No | Passwort für die Anmeldung per Sitzung, für Versionen vor 0.19.0 oder ohne Schlüssel | |
| NKF_USERNAME | No | Anmeldung per Sitzung, für Versionen vor 0.19.0 oder ohne Schlüssel | |
| NKF_RECEIPT_DIR | No | Wenn gesetzt, lädt der Server nur Belege aus diesem Ordner hoch (empfohlen) | |
| NKF_NO_RECORD_PROMPT | No | 1 schaltet die Nachfrage von Claude Code bei jedem Erfassen ab |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Dieser Server verbindet dich mit NebenkostenFix, einer App für private Vermieter, die Nebenkostenabrechnungen nach BetrKV und HeizkostenV erstellt. Du kannst den Bestand lesen (Immobilien, Wohnungen, Mieter, Rechnungen, Zähler, Zahlungen, Fristen, Abrechnungen) und Abrechnungen vorprüfen, ohne etwas zu verändern.
Beginne bei Unklarheit mit check_connection.
IDs (Immobilie, Mieter, Kostenart, Zähler) ermittelst du über die Lese-Werkzeuge, rate sie nie.
Geldbeträge sind Strings mit Punkt und zwei Nachkommastellen ("1234.56"), in Euro.
Ändern oder löschen kann dieser Server nichts; Korrekturen macht der Mensch in NebenkostenFix.
Einen Überblick über Immobilien, Mieter (mit IDs), Abrechnungen, die noch offen oder nicht zugestellt sind, und nahe Fristen gibt die Resource nkfix://overview; du liest sie mit ReadMcpResourceTool (Server nkfix), wenn dein Client das anbietet.
Anlegen kannst du mit record_payment, record_meter_reading, record_invoice (auch mit Beleg) und upload_invoice_document. Ruf sie nur auf, wenn der Mensch dem Eintrag zugestimmt hat, und nenne ihm vorher die Werte. Bei einem Beleg mit mehreren Rechnungen: erst upload_invoice_document, dann jede Rechnung mit invoice_document_id.
Eine Nachzahlung auf eine Abrechnung (Nebenkostenzahlung, Guthabenauszahlung negativ) erfasst du mit statement_id; die Abrechnung ermittelst du mit list_statements. Ohne sie zählt die Zahlung dort nicht.
Kommt „saved: false“ mit Bedenken zurück, frag den Menschen. Den Freigabecode aus der Antwort schickst du nur nach seiner ausdrücklichen Zustimmung mit, nie vorab und nie von dir aus.
Lehnt der Mensch ab oder lässt sich etwas nicht erfassen, sag ihm, dass er den Eintrag selbst in NebenkostenFix anlegen kann.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| completions | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| check_connectionA | Prüft die Verbindung zu NebenkostenFix: angemeldetes Konto, Zugriffsschlüssel und dessen Umfang (lesen oder erfassen), Version der Instanz und Warnungen. Liest nur. |
| list_propertiesA | Alle Immobilien (Häuser bzw. Objekte) mit ID und Name. Ausgangspunkt für fast alle anderen Werkzeuge. |
| list_apartmentsC | Die Wohnungen bzw. Einheiten einer Immobilie mit Fläche und Nutzungsart. |
| list_heating_systemsB | Die Heizungsanlagen einer Immobilie (für Heizkostenrechnungen nach HeizkostenV). |
| list_tenantsC | Mieter mit Wohnung, Ein- und Auszug und dem Datum, bis zu dem zuletzt abgerechnet wurde. |
| get_advance_payment_statusB | Soll und Ist der Nebenkostenvorauszahlungen eines Mieters je Monat, mit offenem Betrag und Saldo. |
| list_paymentsB | Eingegangene Zahlungen von Mietern (Miete, Vorauszahlungen, Kaution, Nachzahlungen), neueste zuerst. |
| list_cost_categoriesA | Kostenarten (Betriebskostenarten nach BetrKV) mit Umlageschlüssel. Die ID braucht man zum Erfassen von Rechnungen. |
| list_providersC | Dienstleister bzw. Versorger (Rechnungssteller), die in NebenkostenFix angelegt sind. |
| list_invoicesA | Rechnungen (Kosten) mit Betrag, Zeitraum, Kostenart und ob ein Beleg hinterlegt ist. Eine Rechnung zählt zu einem Jahr, wenn sich ihr Zeitraum mit dem Jahr überschneidet. |
| list_invoice_documentsB | Hochgeladene Belege, die mehrere Rechnungen enthalten können (Sammelbelege). |
| list_metersA | Die Zähler einer Immobilie mit ihrem neuesten Stand; mit meter_id die letzten Stände dieses Zählers. |
| list_deadlinesA | Anstehende Termine und Fristen: Abrechnungs-, Einwendungs- und Eichfristen, Ablesungen, neue Vorauszahlungen und die früheste Mieterhöhung. Abrechnungs- und Einwendungsfristen nennen die Abrechnung (statement_id) und ihren Abrechnungszeitraum. |
| get_data_qualityA | Prüft den Datenbestand einer Immobilie: veraltete Zählerstände und fehlende Zähler. |
| get_billing_year_statusA | Stand des Jahresabschlusses einer Immobilie: Kosten je Kostenart im Abrechnungsjahr (zeitanteilig) mit Vorjahr, fehlende Ablesungen, Mieter mit ihren Abrechnungen, offene Punkte (open_issues) und die Abrechnungsfrist. |
| list_billing_suggestionsC | Mieter, für die eine Nebenkostenabrechnung fällig ist, mit vorgeschlagenem Zeitraum. |
| list_statementsB | Erstellte Nebenkostenabrechnungen mit Zeitraum, Zustellung und offenem Betrag. |
| get_statementC | Ergebnis einer Abrechnung: Kosten je Position mit Anteil des Mieters, Vorauszahlungen, Saldo, Anpassung der Vorauszahlung und Fristen. |
| precheck_statementA | Prüft, ob sich eine Nebenkostenabrechnung für den Mieter und Zeitraum erstellen lässt: fehlende Rechnungen und Zählerstände, Überschneidung mit bestehenden Abrechnungen, Abrechnungsfrist. Ein Ende in der Zukunft kürzt NebenkostenFix auf heute. Erstellt keine Abrechnung und ändert nichts. |
| check_meter_readingA | Prüft, ob ein Zählerstand zu den bisherigen Ablesungen passt. NebenkostenFix vergleicht nur mit einer Ablesung, die höchstens 30 Tage entfernt ist (beim Hauptzähler mit der Summe der Unterzähler); ohne sie ist checked=false. Speichert nichts. |
| check_hausgeldA | Prüft eine Hausgeld-Einzelabrechnung einer Eigentumswohnung: welche Positionen auf den Mieter umlagefähig sind (BetrKV), ob der eigene Anteil richtig berechnet ist und ob die Summe stimmt. Speichert nichts. |
| record_paymentA | Legt in NebenkostenFix eine eingegangene Zahlung eines Mieters an (schreibt, ändert nichts Bestehendes). Gibt es dieselbe Zahlung schon, wird vorher nachgefragt. Eine Nachzahlung gehört an ihre Abrechnung (statement_id); fehlt sie oder weicht der Betrag vom offenen Betrag ab, wird nachgefragt. |
| record_meter_readingA | Legt in NebenkostenFix einen abgelesenen Zählerstand an (schreibt, ändert nichts Bestehendes). Vorher wird geprüft, ob er zu den bisherigen Ständen passt; bei Bedenken wird nachgefragt. Zähler selbst legt nur der Mensch an: gibt es keinen passenden Zähler, sag das, statt etwas anderes zu erfassen. |
| record_invoiceA | Legt in NebenkostenFix eine Rechnung (Kosten einer Immobilie) an, auf Wunsch mit dem Beleg als Datei (schreibt, ändert nichts Bestehendes). Gibt es schon eine Rechnung mit derselben Nummer oder mit gleicher Kostenart, gleichem Betrag, Zeitraum und Wohnung, wird vorher nachgefragt. Den Inhalt eines Belegs liest du selbst; NebenkostenFix hat keine Texterkennung. |
| upload_invoice_documentA | Lädt einen Beleg mit mehreren Rechnungen (z. B. Jahresabrechnung der Stadtwerke) zu einer Immobilie hoch (schreibt, ändert nichts Bestehendes). Danach legst du jede Rechnung darauf mit record_invoice und invoice_document_id an. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| prepare_year_end | Geht den Stand eines Abrechnungsjahrs durch: Rechnungen, Zählerstände, Abrechnung oder Vorprüfung je Mieter, Fristen. Am Ende steht, was fehlt und was auffällt. Ändert nichts. |
| check_hausgeld_statement | Prüft eine angehängte Hausgeld-Einzelabrechnung der WEG: umlagefähig oder nicht, eigener Anteil, Summenprobe. |
| record_receipt | Liest einen Beleg, prüft auf Dubletten und erfasst die Rechnung nach deiner Zustimmung. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| overview | Immobilien mit ihren Mietern (samt IDs), Abrechnungen, die noch offen oder nicht zugestellt sind, und die Fristen der nächsten 90 Tage, als Markdown. |
| deadlines | Alle anstehenden Fristen und Termine: Abrechnungs-, Einwendungs- und Eichfristen, Ablesungen, neue Vorauszahlungen und die früheste Mieterhöhung. |
TDQS
Scored across 25 tools
Most tools target a distinct resource (properties, apartments, tenants, invoices, meters, statements) or a clearly differentiated action (check vs record vs upload). The diagnostic tools overlap somewhat: get_data_quality, get_billing_year_status and precheck_statement all report missing readings/invoices and deadlines for a property, so an agent may hesitate between them. Descriptions provide enough cues (precheck is tenant+period bound, year status is per property-year) to keep them separable.
Every tool is snake_case with a clear verb_noun pattern: list_*, get_*, check_*, record_*, upload_*, precheck_statement. The verbs are used consistently by intent (read vs validate vs write), and there are no mixed camelCase or vague standalone names.
25 tools is at the heavy end for a single billing domain, and the read surface is dense: 14 list_* plus three overlapping diagnostic endpoints. The domain is genuinely broad (properties, tenants, costs, meters, statements, deadlines), but a few tools could be merged without losing capability.
The write surface is deliberately append-only (record_payment, record_meter_reading, record_invoice, upload_invoice_document) and read coverage is strong, but there is a notable dead end: statements can be listed, inspected and prechecked but never created, and no tool exists to add tenants, properties, cost categories or to correct/update existing records. Many workflows therefore require manual human action mid-stream.