open-splitwise

Verwandle Splitwise in einen agenten-nativen Ausgaben-Tracker.

Ein offener Model Context Protocol (MCP)-Server, der es jedem KI-Agenten — Hermes, Claude Desktop, Claude Code, Cursor oder allem, was MCP spricht — ermöglicht, Salden zu lesen, Ausgaben aus unstrukturierter natürlicher Sprache aufzuteilen, eigene Authentifizierungsprobleme zu diagnostizieren und sich nie Gedanken über Ratenlimits zu machen.

Python 3.11+ · MCP spec 2026-07-28 · stdio transport · 33 tools · lazy-loaded

Warum

Bestehende Splitwise-Integrationen geben dem Modell einen rohen API-Spiegel und hoffen auf das Beste. Das scheitert auf vorhersehbare Weise: Das Modell erfindet Kategorie-IDs, teilt ₹300 falsch auf drei Personen auf, glaubt Splitwises 200 OK, obwohl die Anfrage tatsächlich fehlgeschlagen ist, oder behandelt eine Rate-Limit-Antwort als Fehler, den es aggressiv erneut versuchen soll.

open-splitwise behebt dies auf der Server-Ebene:

Features

• Vollständige API-Abdeckung — alle 27 Endpunkte der offiziellen Splitwise-OpenAPI-3.0-Spezifikation, ein Tool pro Endpunkt, originalgetreue Namen.

• Workflow-Ebene — High-Level-Tools, sodass eine einzelne Äußerung einem einzelnen Aufruf entspricht.

• Self-Service-Authentifizierungslebenszyklus — setup_auth validiert einen Schlüssel live gegen Splitwise, bevor er gespeichert wird (falsche Schlüssel werden nie gespeichert), get_auth_status erklärt, was konfiguriert ist, logout löscht Anmeldedaten. Eine erneute Authentifizierung funktioniert mitten in der Sitzung.

• Ehrliche Fehler — jeder Fehlermodus (nicht aufgelöste Person, Anteilssummen-Konflikt, unbekannte Kategorie, widerrufener Schlüssel, erschöpfte Wiederholungsversuche) gibt Text zurück, der dem Agenten genau sagt, was passiert ist und was als Nächstes zu tun ist.

• Standardmäßig sichere Anmerkungen — Lesevorgänge tragen readOnlyHint, destruktive Löschungen tragen destructiveHint, gemäß MCP-2026-07-28-Semantik. Tools registrieren sich in deterministischer Reihenfolge für cache-freundliche Erkennung.

• Lokale Geheimnisse — API-Schlüssel wird unter ~/.config/splitwise-mcp/credentials.json gespeichert, Modus 0600, atomare Schreibvorgänge, niemals ausgegeben (nur maskierte Vorschauen).

Schnellstart

git clone https://github.com/<you>/open-splitwise.git
cd open-splitwise
uv sync

Führe es eigenständig aus (stdio):

uv run open-splitwise          # starts with no key configured — see auth below

Hole dir einen API-Schlüssel unter https://secure.splitwise.com/apps (Kontoeinstellungen → API-Schlüssel).

Verbinde einen beliebigen MCP-Client

Generischer stdio-Block (Claude Desktop claude_desktop_config.json, Claude Code .mcp.json, Cursor, …):

{
  "mcpServers": {
    "splitwise": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/open-splitwise", "run", "open-splitwise"],
      "env": { "SPLITWISE_API_KEY": "<optional: preconfigure>" }
    }
  }
}

Hermes-Agent verbinden

Füge zu ~/.hermes/config.yaml hinzu:

mcp_servers:
  splitwise:
    command: "uv"
    args: ["--directory", "/absolute/path/to/open-splitwise", "run", "open-splitwise"]
    env:
      SPLITWISE_API_KEY: "<optional>"
    tools:
      include: [quick_add_expense, resolve_users, money_summary, get_auth_status]
    prompts: false
    resources: false

Dann /reload-mcp. Beginne mit den vier Workflow-/Auth-Tools oben; füge rohe API-Tools nur bei Bedarf hinzu — Hermes' serverseitige Filterung hält den Tool-Umfang klein.

Authentifizierungslebenszyklus

Der Server ist so konzipiert, dass Agenten Authentifizierungsprobleme selbst diagnostizieren und beheben und dich nur nach dem Geheimnis fragen:

Die Schlüsselauflösung erfolgt pro Anfrage: gespeicherte Anmeldeinformation → SPLITWISE_API_KEY-Umgebungsvariable → keine. Ein frisch gespeicherter Schlüssel wird sofort im laufenden Prozess wirksam — keine Neustarts.

Anmeldedaten liegen unter ~/.config/splitwise-mcp/credentials.json (Modus 0600). Überschreibe das Verzeichnis mit SPLITWISE_MCP_CONFIG_DIR (praktisch für Tests oder Multi-Profil-Setups).

Agenten-Ergonomie

You:      "add dinner 900 split with alice and bob@x.com, groceries"
Agent:    quick_add_expense(description="Dinner", cost="900.00",
                            participants=["alice", "bob@x.com"],
                            category_name="groceries")
Server:   resolves alice→12? two matches! → error listing Alice A (id 10), Alice Wood (id 12)
Agent:    "Which Alice?"  → you answer → re-call succeeds
Server:   { status: created, expense_id: 99123,
            splits: [ "Nikhil paid 900.00 INR",
                      "Alice A owes 300.00 INR",
                      "Bob B owes 300.00 INR" ] }

• quick_add_expense — Namen/Teilnamen/E-Mails/IDs werden akzeptiert; gleiche Anteile werden berechnet, Restcents deterministisch verteilt; benutzerdefinierte owed_shares werden auf exakte Summe validiert; Zahler standardmäßig enthalten (include_payer_in_split=false, wenn sie nicht konsumiert haben); Währung standardmäßig aus deinem Profil.

• resolve_users — E-Mail-Exaktübereinstimmung, Vollnamen-Übereinstimmung, eindeutiger Vorname, Teilstring-Fallback; Mehrdeutigkeit gibt Kandidaten zurück, anstatt zu raten.

• money_summary — pro Währung owed_to_you / you_owe / net, Freundes-Salden und vereinfachte Gruppenschulden, an denen du beteiligt bist.

Tool-Referenz (33)

* mit destructiveHint=true annotiert; alle get_*-Tools sind mit readOnlyHint=true annotiert. Bevorzuge Workflow-Tools gegenüber ihren rohen Gegenstücken, wann immer beide existieren.

Ratenlimitierung

Splitwise antwortet mit HTTP 429, wenn gedrosselt wird. open-splitwise wiederholt automatisch: Retry-After-Header wird wörtlich beachtet; andernfalls exponentielles Backoff (0,5 s Verdopplung, begrenzt auf 30 s), standardmäßig bis zu 3 Versuche. Agenten sehen nur dann einen Fehler, wenn alle Versuche erschöpft sind — und dieser Fehler sagt, langsamer zu machen, nicht blind zu wiederholen.

Konfiguration

Splitwise-Eigenheiten, die für dich behandelt werden

• Array-Parameter werden in Splitwises seltsame users__{index}__{property}-Kodierung umgewandelt

• 200 OK ≠ Erfolg: errors{} / success:false werden bei jeder Mutation geprüft

• Geld als Dezimal-Zeichenketten mit 2 Nachkommastellen; Restcents werden verteilt, Summen sind immer exakt

• category_id muss eine Unterkategorie sein — durchgesetzt über unscharfe Namensauflösung

• Salden/Schulden werden aus vorberechneten balance[] / simplified_debts gelesen (niemals neu berechnet)

• „Settle up" ist nur eine Ausgabe mit payment:true (es gibt keinen dedizierten Endpunkt)

• OAuth2 existiert, ist aber bewusst außerhalb des Rahmens: Persönliche API-Schlüssel passen zum Agent-fragt-Benutzer-Ablauf; OAuth benötigt eine Redirect-URI + Browser (nur für gehostete Bereitstellungen)

Architektur

┌─────────────── any MCP client ───────────────┐
│  Hermes / Claude Desktop / Cursor / …        │
└──────────────────┬───────────────────────────┘
                   │ JSON-RPC over stdio
┌──────────────────▼───────────────────────────┐
│ server.py — FastMCP app, 33 tools            │
│   workflows · raw endpoints · auth lifecycle │
├──────────────────────────────────────────────┤
│ client.py — async REST client                │
│   bearer auth (per-request key resolution)   │
│   param flattening · success verification    │
│   transparent 429 retry/backoff              │
├──────────────────────────────────────────────┤
│ auth.py — credentials.json (0600, atomic)    │
└──────────────────┬───────────────────────────┘
                   │ HTTPS
          secure.splitwise.com/api/v3.0

Entwicklung

uv run pytest                        # 54 tests: client, rate limits, auth, workflows, lazy loading, MCP semantics
uv run python scripts/smoke_stdio.py # real subprocess: handshake, discovery, live auth-failure paths

Test-first entwickelt (strikte TDD): Jedes oben genannte Verhalten hat eine Test-first-Herkunft (zuerst fehlschlagender Test). Layout:

src/open_splitwise/
  client.py    # REST client: auth provider, flattening, retry, error mapping
  auth.py      # credential storage
  server.py    # FastMCP definitions: workflows + raw + auth tools
tests/
scripts/smoke_stdio.py

Nutzungsbedingungen

Die Self-Service-API von Splitwise ist laut ihren API-Bedingungen nicht kommerziell. Dein API-Schlüssel gewährt vollen Zugriff auf dein Konto — behandle ihn wie ein Passwort. Dieses Projekt ist eine unabhängige Integration und wird von Splitwise Inc. weder unterstützt noch befürwortet.

Roadmap

• Beleg-Upload bei der Ausgabenerstellung

• Multi-Währungs-Ausgaben-Helfer mit Umrechnungsunterstützung

• Zusammenfassungen wiederkehrender Ausgaben als MCP-Prompt

• Optionaler Streamable-HTTP-Transport für gehostete/Multi-Benutzer-Bereitstellungen (+OAuth2)

• Veröffentlichung auf PyPI (uvx open-splitwise)

Mitwirken

PRs sind willkommen — bitte halte die TDD-Disziplin ein (Tests schlagen zuerst fehl, dann bestehen sie), schreibe Tool-Beschreibungen weiterhin für Modelle und protokolliere niemals Geheimnisse.

Lizenz

MIT — offen für alle: nutze es, modifiziere es, veröffentliche es, verkaufe es. Behalte nur den Urheberrechtshinweis.