Finance Tracker MCP

Servidor MCP (stdio) y cliente headless para Finance Tracker. Se ejecuta en la máquina del usuario: descifra y cifra en local, y solo envía ciphertext al servidor.

Uso

Requisito: Node.js 20 o superior.

1. En la app: Configuración → Acceso por API → Crear token (con la bóveda desbloqueada). Copia la configuración que aparece.
2. Pégala en tu cliente MCP (Claude Desktop, Claude Code, Cursor…):

   {
     "mcpServers": {
       "finance-tracker": {
         "command": "npx",
         "args": ["-y", "finance-tracker-mcp@latest"],
         "env": {
           "FT_SUPABASE_URL": "…",
           "FT_SUPABASE_ANON_KEY": "…",
           "FT_API_TOKEN": "ftk_…"
         }
       }
     }
   }

Desarrollo

cd mcp && npm install
npm run build                          # genera dist/finance-mcp.mjs
FT_API_TOKEN=ftk_… npm run test:e2e    # prueba contra un proyecto real
npm version patch && npm publish       # publica una versión nueva

Herramientas

| Tool | Qué hace | | --- | --- | | list_categories / list_saving_goals / list_recurrent_transactions | Lectura | | list_transactions | Con filtros from, to, category_id, status, limit | | get_summary | Ingresos, gastos y totales por categoría en un rango | | add_transaction / update_transaction / delete_transaction | Escritura | | add_category | Crea categoría |

Sin MCP

src/client.ts (FinanceApiClient) se puede usar directamente desde cualquier script de Node ≥ 20:

const api = await FinanceApiClient.connect({ supabaseUrl, supabaseAnonKey, apiToken });
await api.addTransaction({ date: new Date().toISOString(), concept: 'Café', amount: 2.5, category_id, payment_method: 'Tarjeta' });

Seguridad

• Del token se derivan dos claves (HKDF): una para autenticarse (el servidor guarda solo su hash) y otra que desenvuelve la DEK y nunca sale de esta máquina.
• Revocar un token corta el acceso al servidor al instante. Si se sospecha que alguien llegó a usarlo, la única protección completa es rotar la DEK.
• El modelo de IA ve los datos en claro que devuelven las herramientas.