quickbooks-mcp-server

Ein MCP-Server aus einer einzigen Datei, der Claude Desktop vollen Lese- und Schreibzugriff auf QuickBooks Online gibt, plus Abgleich-Tools, die jene Dinge finden, die einem Menschen beim Durchscrollen eines Kontenregisters entgehen.

$ qbo_health_check

  transport ...... stdio (Claude Desktop, Claude Code, claude.ai)
  api ............ QuickBooks Online v3
  tools .......... 22
  version ........ 2.0.0
  deploy ......... local, or HTTP on a Raspberry Pi behind Tailscale

Warum es das hier gibt

Buchhaltungsfragen sind fast nie eine einzelne Abfrage. „Haben wir diesen Lieferanten wirklich doppelt bezahlt?" bedeutet: Einkäufe auflisten, nach Betrag und zeitlicher Nähe groupieren, den Abgleich mit dem Bank-Feed vornehmen und dann prüfen, ob das Duplikat später storniert wurde. Das ist eine Schleife – und für Schleifen immer wieder der Agent gedacht.

Der Design-Grundansatz: Dem Modell eine kleine Menge kombinierbarer Tools geben und es selbst denken lassen, statt ein einziges großes reconcile() beizu, das meine Beurteilung darüber, was eine Abweichung bedeutet, in Sperrstein codiert.

Genau deshalb hat v2.0.0 22 Tools statt 45 in v1.0.0 – die erste Version hatte ein Tool für jede jemals von mir gestellte Frage. Es stellte sich heraus, dass es deren meisten nur aus zwei Grundbausteinen komponiet. Chessives Modell waren – also blieben die Grundbausteine, die Ok ausgeführten Tools wurden gelöscht. Die Migrationsübersicht wurde in CHANGELOG.md.

How to improve? Let's deliver the whole translated message well.

Given the user's "Return only the translated text" – our final answer should be one document. I'll now write a complete final output, checking each paragraph.

One point: "Grundbausteine" translating "primitives" okay. But "mess" word "Menge" fine.

Let's produce# quickbooks-mcp-server

Ein MCP-Server aus einer einzigen Datei, der Claude Desktop vollen Lese- und Schreibzugriff auf QuickBooks Online gibt, plus Abgleich-Tools, die genau das finden, was eine menschliche Person beim Durchscrollen eines Kontos nicht bemerkt.

$ qbo_health_check

  transport ...... stdio (Claude Desktop, Claude Code, claude.ai)
  api ............ QuickBooks Online v3
  tools .......... 22
  version ........ 2.0.0
  deploy ......... local, or HTTP on a Raspberry Pi behind Tailscale

Related MCP server: penni-mcp

Warum es das hier gibt

Buchhaltungsfragen sind fast nie doch eigentlich eine einzelne Abfrage. „Haben wir diesen Lieferanten wirklich doppelt bezahlt?" bedeutet: Einkäufe auflisten, nach Betrag und zeitlicher Nähe gruppieren, mit dem Bank-Feed abgleichen und anschließend prüfen, ob das Duplikat später storniert wurde. Das ist eine Schleife – und Schleifen sind genau das, wofür ein Agent da ist.

Der Design-Grundsatz: Dem Modell eine kleine Menge kombinierbarer Tools geben und es selbst schlussfolgern lassen, statt ein großes reconcile() mitzuliefern, das meine Beurteilung darüber einbau, was eine Abweichung bedeutet.

Genau deshalb umfasst v2.0.0 22 Tools statt 45 in v1.0.0. Die erste Version hatte für jede Frage, die ich mir je gestellt habe, ein Tool. Es zeigte sich, dass die meisten davon daraus bestanden, dass das Modell zwei Grundbausteine miteinander kombinierte – also blieben die Grundbausteine erhalten und die zusammengesetzten Tools wurden gelöscht. Die Migrationsübersicht findest du in CHANGELOG.md.

Tools

$ qbo --list-tools

  read
    qbo_company_info            qbo_get_preferences         qbo_health_check
    qbo_list_accounts           qbo_list_customers          qbo_get_customer
    qbo_list_bills              qbo_list_deposits           qbo_get_entity
    qbo_get_invoice             qbo_get_transaction         qbo_get_transfer
    qbo_get_journal_entry       qbo_get_report              qbo_account_register

  write
    qbo_create_invoice          qbo_create_payment          qbo_create_purchase
    qbo_delete_journal_entry    qbo_delete_purchase         qbo_delete_transfer
    qbo_batch_delete

  reconciliation
    qbo_detect_bank_feed_gaps       find dates where the feed silently stopped
    qbo_find_duplicate_transactions near-match scan across amount + date window
    qbo_duplicate_scan_by_account   the same, scoped to one account
    qbo_analyze_reconciliation      month-end variance with the arithmetic shown

Die Abgleich-Tools sind die, die man übernehmen sollte. Lücken im Bank-Feed sind der Fehlerfall, den keiner klampft – ein 4 Tage lang stoppt, Transaktionen nie ankommen und die Bücher einem unvollständigen Bild gegenüber perfekt ausgeglichen bleiben. Keine Fehlermeldung. Man sieht es erst im März nach Jahresableitung.

Installation

$ git clone https://github.com/rjpaganini/quickbooks-mcp-server
$ cd quickbooks-mcp-server
$ pip install -r requirements.txt
$ cp .env.example .env        # then fill in your QBO app credentials

Registriere eine App unter developer.intuit.com, um eine Client-ID und ein Secret zu erhalten. Du brauchst dann:

  QB_REALM_ID          your company id
  QB_CLIENT_ID         from the Intuit developer app
  QB_CLIENT_SECRET     from the Intuit developer app
  QB_REFRESH_TOKEN     from the OAuth playground
  QB_ACCESS_TOKEN      refreshed automatically once seeded
  QB_SANDBOX           true while testing — set false deliberately

Danach richtest du deinen MCP-Client auf ihn aus:

{
  "mcpServers": {
    "quickbooks": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

Sicherheit

Dieser Server kann Dinge in echten Buchhaltungsdaten löschen. Das ist nicht hypothetisch – qbo_batch_delete existiert, weil das Bereinigen eines fehlerhaften Imports von Hand einzige Qual ist.

Lies das SECURITY.md ebenso, bevor du ihn auf eine echte Firmendatei rightest. Die Kurfassung: Starte in der Sandbox, behalte Die Sandbox bei, bis du das Ganze hast arbeiten sehen, und fechte die Schreib- und Lösch-Tools wie rm mit einem wildcard.

$ pytest                       # unit tests, no network
$ pytest -m live               # smoke tests against a live sandbox company

Notes

• Datei bewusst eine einzige Datei. server.py ist groß, aber mit namespace Dinger sowie das Alles ist grep-fähig und man muss seinen Importgraph nicht immer gedanklich mitnehmen.

• Sie läuft auch über den HTTP-Dienst auf einem Raspberry Pi mithilfe von deploy-to-pi.sh, was den Zugriff von claude.ai aus einem Handy über Tailscale ermöglicht.

• Keine Anmeldedaten, Unternehmensdaten oder Finanzdaten liegen in diesem Erfolgsprojekt bereit.

Diese Lizenz ist MIT.

MIT.