open-splitwise

Convierte Splitwise en un rastreador de gastos nativo para agentes.

Un servidor abierto del Model Context Protocol (MCP) que permite a cualquier agente de IA — Hermes, Claude Desktop, Claude Code, Cursor, o cualquier cosa que hable MCP — leer saldos, dividir gastos a partir de lenguaje natural desordenado, diagnosticar sus propios problemas de autenticación y no preocuparse nunca por los límites de tasa.

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

Por qué

Las integraciones existentes de Splitwise le dan al modelo un espejo crudo de la API y esperan lo mejor. Eso falla de maneras predecibles: el modelo inventa IDs de categoría, divide mal ₹300 entre tres, cree en el 200 OK de Splitwise cuando la solicitud realmente falló, o trata una respuesta de límite de tasa como un error que debe reintentar agresivamente.

open-splitwise soluciona esto en la capa del servidor:

Características

• Cobertura completa de la API — los 27 endpoints de la especificación oficial Splitwise OpenAPI 3.0, una herramienta para cada uno, nombres fieles.

• Capa de flujo de trabajo — herramientas de alto nivel para que una sola expresión se corresponda con una sola llamada.

• Ciclo de vida de autenticación de autoservicio — setup_auth valida una clave en vivo contra Splitwise antes de almacenarla (las claves incorrectas nunca se persisten), get_auth_status explica qué está configurado, logout borra las credenciales. La reautenticación funciona a mitad de sesión.

• Errores honestos — cada modo de fallo (persona no resuelta, discrepancia en la suma de participaciones, categoría desconocida, clave revocada, reintentos agotados) devuelve texto que le dice al agente exactamente qué ocurrió y qué hacer a continuación.

• Anotaciones seguras por defecto — las lecturas llevan readOnlyHint, los borrados destructivos llevan destructiveHint, según la semántica de MCP 2026-07-28. Las herramientas se registran en orden determinista para un descubrimiento amigable con la caché.

• Secretos locales primero — la clave de API se almacena en ~/.config/splitwise-mcp/credentials.json, modo 0600, escrituras atómicas, nunca se devuelve (solo vistas previas enmascaradas).

Inicio rápido

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

Ejecútalo de forma independiente (stdio):

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

Obtén una clave de API en https://secure.splitwise.com/apps (Configuración de la cuenta → Claves de API).

Conecta cualquier cliente MCP

Bloque stdio genérico (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>" }
    }
  }
}

Conecta Hermes Agent

Añade a ~/.hermes/config.yaml:

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

Luego /reload-mcp. Comienza con las cuatro herramientas de flujo de trabajo/autenticación anteriores; añade herramientas de API crudas solo cuando sea necesario — el filtrado por servidor de Hermes mantiene la superficie de herramientas pequeña.

Ciclo de vida de autenticación

El servidor está diseñado para que los agentes diagnostiquen y arreglen la autenticación por sí mismos, pidiéndote solo el secreto:

La resolución de claves ocurre por solicitud: credencial almacenada → variable de entorno SPLITWISE_API_KEY → ninguna. Una clave recién guardada surte efecto inmediatamente en el proceso en ejecución — cero reinicios.

Las credenciales viven en ~/.config/splitwise-mcp/credentials.json (modo 0600). Sobrescribe el directorio con SPLITWISE_MCP_CONFIG_DIR (útil para pruebas o configuraciones de múltiples perfiles).

Ergonomía para agentes

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 — acepta nombres/nombres parciales/emails/IDs; las participaciones iguales se calculan con los céntimos restantes distribuidos de forma determinista; las owed_shares personalizadas se validan para que sumen exactamente; el pagador se incluye por defecto (include_payer_in_split=false cuando no consumió); la moneda se toma por defecto de tu perfil.

• resolve_users — coincidencia exacta de email, coincidencia de nombre completo, nombre propio único, respaldo por subcadena; la ambigüedad devuelve candidatos en lugar de adivinar.

• money_summary — owed_to_you / you_owe / net por moneda, saldos a nivel de amigos y deudas simplificadas de grupo que te involucran.

Referencia de herramientas (33)

* anotadas con destructiveHint=true; todas las herramientas get_* anotadas con readOnlyHint=true. Prefiere las herramientas de flujo de trabajo sobre sus contrapartes crudas cuando ambas existan.

Límites de tasa

Splitwise responde HTTP 429 cuando se limita la tasa. open-splitwise reintenta automáticamente: se respeta la cabecera Retry-After tal cual; de lo contrario, retroceso exponencial (0,5 s duplicando, con tope de 30 s), hasta 3 intentos por defecto. Los agentes ven un error solo si se agotan todos los intentos — y ese error dice que se ralentice, no que reintente a ciegas.

Configuración

Peculiaridades de Splitwise manejadas por ti

• Los parámetros de matriz se aplanan a la extraña codificación users__{index}__{property} de Splitwise

• 200 OK ≠ éxito: se comprueba errors{} / success:false en cada mutación

• Dinero como cadenas decimales con 2 decimales; los céntimos restantes se distribuyen, las sumas siempre exactas

• category_id debe ser una subcategoría — se aplica mediante resolución difusa de nombres

• Los saldos/deudas se leen de balance[] / simplified_debts precalculados (nunca se recalculan)

• «Settle up» es solo un gasto con payment:true (no existe un endpoint dedicado)

• OAuth2 existe pero está deliberadamente fuera de alcance: las claves de API personales encajan en el flujo de agente-pregunta-al-usuario; OAuth necesita una URI de redirección + navegador (solo implementaciones alojadas)

Arquitectura

┌─────────────── 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

Desarrollo

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

Construido con test-first (TDD estricto): cada comportamiento anterior tiene una procedencia de prueba que falla primero. Estructura:

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

Términos de uso

La API de autoservicio de Splitwise es no comercial según sus términos de API. Tu clave de API otorga acceso completo a tu cuenta — trátala como una contraseña. Este proyecto es una integración independiente y no está afiliado ni respaldado por Splitwise Inc.

Hoja de ruta

• Subida de recibos al crear gastos

• Asistente de gastos multidivisa con conocimiento de conversión

• Resúmenes de gastos recurrentes como prompt de MCP

• Transporte HTTP Streamable opcional para implementaciones alojadas/multiusuario (+OAuth2)

• Publicar en PyPI (uvx open-splitwise)

Contribuciones

Se aceptan PRs — por favor mantén la disciplina TDD (las pruebas fallan primero, luego pasan), mantén las descripciones de herramientas escritas para modelos, y nunca registres secretos.

Licencia

MIT — abierto para todos: úsalo, modifícalo, publícalo, véndelo. Solo conserva el aviso de copyright.