splitwise-mcp

Un servidor MCP (Model Context Protocol) local que expone la API de Splitwise como herramientas, para que los clientes MCP (Claude Desktop, Claude Code, etc.) puedan leer y gestionar gastos, grupos y amigos de forma conversacional.

Se ejecuta completamente en local sobre stdio — sin alojamiento, sin punto final público, ningún dato sale de tu máquina excepto las llamadas directas a secure.splitwise.com.

Este es un proyecto independiente y no oficial. No está afiliado, respaldado ni soportado por Splitwise, Inc.

Requisitos: Node.js 18+ y una clave de API personal de Splitwise.

Herramientas

La API de Splitwise no tiene un punto final nativo para operaciones masivas — las herramientas masivas realizan las mismas llamadas por gasto que create_expense/delete_expense, con hasta 5 solicitudes en vuelo a la vez, y reportan un resultado por elemento (ok/error) para que un fallo parcial no pierda el resto del lote.

Related MCP server: Splitwise MCP Server

Configuración

1. Obtén una clave de API de Splitwise: ve a secure.splitwise.com/apps, registra una aplicación y copia la clave de API personal que te proporciona.

2. Instala las dependencias y compila:

   npm install
   npm run build

3. Ejecuta las pruebas (opcional, pero recomendado antes de conectarlo a un cliente):

   npm test

Configuración del cliente

Añade a la configuración de tu cliente MCP (por ejemplo, claude_desktop_config.json de Claude Desktop, o .mcp.json de Claude Code):

{
  "mcpServers": {
    "splitwise": {
      "command": "node",
      "args": ["/absolute/path/to/splitwise-mcp/build/index.js"],
      "env": {
        "SPLITWISE_API_KEY": "your-personal-api-key"
      }
    }
  }
}

Una vez publicado en npm (como @tbmueller/splitwise-mcp — el nombre sin ámbito pertenece a un proyecto no relacionado), esto puede ser en su lugar:

{
  "mcpServers": {
    "splitwise": {
      "command": "npx",
      "args": ["-y", "@tbmueller/splitwise-mcp"],
      "env": { "SPLITWISE_API_KEY": "your-personal-api-key" }
    }
  }
}

Nunca comitees tu clave de API. Mantenla solo en la configuración de tu cliente MCP o en un archivo .env local, ignorado por git — nunca en una entrada de herramienta, un archivo comiteado, o un argumento de script que pueda terminar en el historial del shell.

Desarrollo

npm run dev          # tsc --watch
npm test             # vitest run
npm run test:watch   # vitest
npm run format       # prettier --write .
npm run format:check # prettier --check . (used in CI)
npm run inspector    # build + launch MCP Inspector against the server

Notas de diseño

• Los montos de dinero se manejan como cadenas decimales de principio a fin (nunca se convierten a float) — la validación de partes para create_expense/update_expense usa aritmética de céntimos enteros.

• Splitwise a veces devuelve HTTP 200 con un objeto errors en el cuerpo en lugar de un estado distinto de 2xx; el cliente verifica el cuerpo, no solo el código de estado.

• Las respuestas se recortan de los campos más ruidosos de Splitwise (avatares, configuraciones de notificación) antes de devolverlas al modelo, para ahorrar contexto.

• Consulta PLAN.md para el plan de diseño original y los candidatos para v2 (gestión de grupos/amigos, comentarios, recursos MCP).

Licencia

MIT