mcp-quipu

MCP-Server für die Quipu-API: Rechnungsstellung, Ausgaben, Kontakte und Buchhaltung für Selbstständige und kleine Unternehmen in Spanien.

Ermöglicht einem Assistenten wie Claude, dein Quipu-Konto in natürlicher Sprache abzufragen und zu verwalten: „Wie viel habe ich dieses Quartal in Rechnung gestellt?“, „Erstelle mir die Septemberrechnung für diesen Kunden.“, „Gib mir das PDF der letzten Rechnung.“

Erstellt von Nubiia. Bruder von mcp-holded.

Status: Alpha (v0.1.0). 18 Tools für Kontakte, Rechnungen, Ausgaben und steuerliche Aggregation. Die übrigen Ressourcen der API sind in docs/api-map.md abgebildet, aber noch nicht freigegeben.

Installation

npm install -g @nubiia/mcp-quipu

Related MCP server: QuickBooks Online MCP Server

Konfiguration

Du benötigst API-Zugangsdaten von Quipu (Einstellungen → API) und den slug deines Kontos, also das erste Segment deiner Quipu-URLs: https://getquipu.com/<slug>/…

{
  "mcpServers": {
    "quipu": {
      "command": "npx",
      "args": ["-y", "@nubiia/mcp-quipu"],
      "env": {
        "QUIPU_CLIENT_ID": "tu_client_id",
        "QUIPU_CLIENT_SECRET": "tu_client_secret",
        "QUIPU_OWNER_SLUG": "tu_slug"
      }
    }
  }
}

Verfügbare Tools

Kontakte

Rechnungen

Zusätzliche Ausgaben und Einnahmen

Steuern

Designhinweise

OAuth2, kein API-Schlüssel. Anders als Holded stellt Quipu Tokens aus, die ablaufen. Der Client legt sie im Cache ab, erneuert sie mit einem Vorlauf von 60 Sekunden und bündelt gleichzeitige Aufrufe zu einer einzigen Anfrage. Bei einem 401 verwirft er das Token und versucht es erneut.

Flaches JSON:API. Quipu gibt { data: { id, attributes: {…} } } zurück. Die Tools glätten die Antwort auf { id, …attributes }, weil Modelle mit flachen Objekten viel besser zurechtkommen und sich Wrapper-Tokens sparen.

Schreiboperationen sind stärker eingeschränkt als Leseoperationen. Eine versehentlich erstellte Rechnung ist keine Zeile in einer Datenbank, sondern ein Dokument mit rechtlichen Folgen. Schreiboperationen haben strengere Kontingente, und die destruktiven sind mit destructiveHint markiert.

Die Steuerarithmetik erfolgt im Code, nicht im Modell. Quipu stellt keinen Endpoint für Steuerformulare (130, 303, 111) bereit, die Zahlen müssen also aus Rechnungen und Ausgaben abgeleitet werden. get_tax_summary durchläuft alle Seiten beider Ressourcen, summiert mit Rundung auf Cent und gibt den bereits berechneten Saldo zurück. Ein Modell zu bitten, eine lange Liste von Beträgen Token für Token zu summieren, ist ein sicherer Weg, eine falsche Steuerzahl zu erhalten.

Die Beträge kommen als Text und mit wenig eindeutigen Namen. Der Basisbetrag ist total_amount_without_taxes und die Steuer ist vat_amount – total und subtotal gibt es nicht. Der Summierer akzeptiert Dezimalkomma, ignoriert leere Werte und schließt einen nicht parsebaren Wert aus und weist in der Antwort darauf hin, anstatt ein stilles NaN weiterzugeben.

Zum Löschen von Rechnungen. Die spanische Gesetzgebung verlangt eine Korrektur per Korrekturrechnung, nicht das Löschen einer bereits nummerierten Rechnung. delete_invoice existiert, weil die API es erlaubt, aber die Beschreibung des Tools weist darauf hin, damit das Modell es nicht leichtfertig vorschlägt.

Entwicklung

npm install
npm run build
npm test
npm run lint

Roadmap

• simplified_invoices — Tickets und vereinfachte Rechnungen (7 Operationen)

• paysheets — Gehaltsabrechnungen (5 Operationen)

• numbering_series, accounting_categories, accounting_subcategories

• attachments und book_entries

• Automatische Auflösung des owner_slug über GET /users/{id}

Lizenz

MIT