gastos-flow-mcp-server

Servidor MCP (Model Context Protocol) para Gastos Flow, una aplicación de seguimiento de gastos personales. Expone todas las operaciones de la API REST como herramientas utilizables desde Claude Desktop u otros clientes MCP.

Herramientas disponibles

| Recurso | Herramientas | |---|---| | Autenticación | login, logout, get_perfil | | Gastos | list, get, create, update, delete | | Ingresos | list, get, create, update, delete | | Categorías de gasto | list, get, create, update, delete | | Orígenes de ingreso | list, create, update, delete | | Monedas | list, create, update, delete | | Cuentas | list, get, create, update, delete | | Personas | list, create, update, delete | | Deudas propias | list, get, create, update, delete, marcar_pagada | | Deudas por cobrar | list, get, create, update, delete, marcar_cobrada | | Gastos recurrentes | list, get, create, update, delete, activar, desactivar |

Instalación

No requiere instalación previa. Se ejecuta directamente con npx:

npx gastos-flow-mcp-server

Configuración en Claude Desktop

Agrega la siguiente entrada en tu claude_desktop_config.json:

{
  "mcpServers": {
    "gastos-flow": {
      "command": "npx",
      "args": ["-y", "gastos-flow-mcp-server"],
      "env": {
        "GASTOS_FLOW_TOKEN": "tu-token-sanctum"
      }
    }
  }
}

El archivo de configuración se encuentra en:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Autenticación

Hay dos formas de autenticarse:

1. Variable de entorno (recomendado): Define GASTOS_FLOW_TOKEN con un token válido de Sanctum antes de arrancar el servidor (como se muestra en la configuración de Claude Desktop arriba).

2. Tool en tiempo de ejecución: Llama a gastos_flow_login con tu email y contraseña. El token se almacena en memoria para el resto de la sesión.

Para obtener un token puedes hacer:

curl -X POST https://gastosflow.com/api/v1/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"tu_password"}'

Desarrollo local

git clone <repo>
cd gastos-flow-mcp
npm install
npm run dev    # Ejecuta con tsx watch (auto-reload al guardar)
npm run build  # Compila TypeScript → dist/
npm start      # Ejecuta el servidor compilado

Modo HTTP

Para correr el servidor en modo HTTP en lugar de stdio:

TRANSPORT=http PORT=3000 npm start

Esto expone el servidor en http://localhost:3000/mcp.

Estructura del proyecto

src/
├── index.ts           # Punto de entrada, registra tools y selecciona transporte
├── constants.ts       # API_BASE_URL, enums (TipoCuenta, Frecuencia, ResponseFormat)
├── types.ts           # Interfaces TypeScript para los objetos de la API
├── services/
│   └── api.ts         # Cliente Axios, almacén de token, manejo de errores
└── tools/
    ├── auth.ts        # Login, logout, perfil
    ├── gastos.ts      # CRUD gastos
    ├── ingresos.ts    # CRUD ingresos
    ├── catalogos.ts   # Categorías, orígenes, monedas, personas
    ├── cuentas.ts     # CRUD cuentas
    ├── deudas.ts      # Deudas propias y por cobrar
    └── recurrentes.ts # Gastos recurrentes