Fintable MCP

Servidor MCP no oficial para fintable.io — gestiona categorías financieras, reglas y transacciones a través de asistentes de IA en lugar de navegar por asistentes de varios pasos.

GitHub
1
Prueba este MCPPatrocinado

Documentación

fintable-mcp

Un servidor MCP (Model Context Protocol) no oficial para fintable.io, que permite a asistentes de IA como Claude gestionar directamente tus categorías financieras, reglas y transacciones — sin tener que pasar por asistentes de varios pasos.

Nota: Este es un proyecto comunitario, no respaldado oficialmente por fintable.io. Funciona comunicándose con el backend Laravel Livewire 3 de Fintable usando la sesión de tu navegador. Si eres el desarrollador de Fintable y te gustaría colaborar en un servidor MCP oficial o en una API pública, abre un issue — ¡nos encantaría trabajar contigo! 🤝

Qué hace

Una vez instalado, puedes pedirle a Claude o a tu cliente MCP favorito cosas como:

  • "Crea estas categorías de gastos: Material de oficina, Envíos, Embalaje, Alquiler de equipos, Suscripciones de software"
  • "Crea reglas: 'Staples' → Material de oficina, 'UPS' → Envíos, 'USPS' → Envíos"
  • "Ejecuta todas las reglas para categorizar mis transacciones"
  • "¿Cuál es el saldo actual de mi cuenta en Ally Bank?"
  • "Enumera todas mis reglas de categorización"

No más navegar por un asistente de 3 páginas 20 veces para configurar 20 categorías. Solo dile a Claude lo que necesitas.

Herramientas proporcionadas

Operaciones de lectura

HerramientaDescripción
fintable_list_accountsEnumera todas las cuentas bancarias conectadas con sus saldos
fintable_list_categoriesEnumera todas las categorías de transacciones
fintable_list_rulesEnumera las reglas de categorización (con paginación)
fintable_list_transactionsEnumera/busca transacciones con filtrado opcional

Operaciones de escritura

HerramientaDescripción
fintable_create_categoryCrea una sola categoría
fintable_create_bulk_categoriesCrea hasta 50 categorías a la vez
fintable_create_ruleCrea una regla de categorización
fintable_create_bulk_rulesCrea varias reglas a la vez
fintable_run_all_rulesEjecuta todas las reglas sobre transacciones sin categorizar
fintable_delete_ruleElimina una regla de categorización
fintable_sync_accountsActiva la sincronización de cuentas bancarias mediante Plaid
fintable_resync_spreadsheetsEnvía actualizaciones a Airtable/Google Sheets

Instalación

Requisitos previos

  • Python 3.10+
  • Una cuenta en fintable.io con cuentas bancarias conectadas
  • Claude Desktop (o cualquier cliente compatible con MCP — Cherry Studio, etc.)

1. Clona este repositorio

git clone https://github.com/jasoncbraatz/fintable-mcp.git
cd fintable-mcp

2. Instala las dependencias

pip install -r requirements.txt

O con uv (más rápido):

uv pip install -r requirements.txt

3. Configuración de autenticación

Tienes dos opciones — automática (recomendada) o manual.

Opción A: Extracción automática de cookies (recomendada)

Instala rookiepy, que lee las cookies directamente de la base de datos local de Chrome usando las credenciales de tu sistema operativo:

pip install rookiepy

Eso es todo. Mientras tengas la sesión iniciada en fintable.io en Chrome, el servidor obtiene cookies frescas en cada ejecución. Sin copiado manual, sin dolores de cabeza por expiración.

Opción A½: Almacén de cookies auto-refrescante (avanzado)

Si quieres que el servidor mantenga su propia sesión sin necesidad de Chrome o rookiepy después de la primera ejecución, añade el indicador --persist-cookies a tu configuración (ver paso 4). Esto guarda las cookies de sesión en ~/.fintable-mcp-cookies.json y las actualiza automáticamente a partir de las respuestas del servidor — la sesión se mantiene viva siempre que no expire del lado del servidor entre ejecuciones.

La semilla inicial proviene del método de autenticación disponible (rookiepy, variable de entorno, etc.). Después de eso, el servidor es autosuficiente.

Nota de seguridad: Esto almacena cookies de sesión en disco. El archivo es un dotfile en tu directorio personal y no se anuncia en ningún sitio, pero cualquier persona con acceso de lectura a tu carpeta personal podría encontrarlo. Si eso te preocupa, quédate con la Opción A.

Nota para Python 3.13+: Es posible que necesites establecer PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1 antes de instalar rookiepy:

PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1 pip install rookiepy

Opción B: Exportación manual de cookies

Si prefieres no instalar rookiepy (o estás usando un navegador distinto de Chrome):

  1. Abre Chrome y ve a fintable.io — asegúrate de haber iniciado sesión
  2. Abre DevTools (F12 o Cmd+Option+I)
  3. Ve a la pestaña Network
  4. Haz clic en cualquier solicitud a fintable.io
  5. Busca el encabezado Cookie en los Request Headers
  6. Copia la cadena de cookies completa

La pasarás como variable de entorno en el siguiente paso.

4. Configura Claude Desktop

Añade lo siguiente al archivo de configuración de Claude Desktop:

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

Si usas rookiepy (Opción A) — no se necesitan variables de entorno:

{
  "mcpServers": {
    "fintable": {
      "command": "python",
      "args": ["/absolute/path/to/fintable-mcp/fintable_mcp.py"]
    }
  }
}

Si usas --persist-cookies (Opción A½) — combínalo con rookiepy o variable de entorno para la semilla inicial:

{
  "mcpServers": {
    "fintable": {
      "command": "python",
      "args": ["/absolute/path/to/fintable-mcp/fintable_mcp.py", "--persist-cookies"]
    }
  }
}

Si usas cookies manuales (Opción B):

{
  "mcpServers": {
    "fintable": {
      "command": "python",
      "args": ["/absolute/path/to/fintable-mcp/fintable_mcp.py"],
      "env": {
        "FINTABLE_COOKIES": "your_full_cookie_string_here"
      }
    }
  }
}

💡 Reemplaza /absolute/path/to/fintable-mcp/fintable_mcp.py con la ruta real donde clonaste este repositorio.

5. Reinicia Claude Desktop

Después de guardar la configuración, cierra y reinicia Claude Desktop por completo. Las herramientas fintable aparecerán en la lista de herramientas de Claude.

Autenticación

Este servidor se autentica usando las cookies de sesión de tu navegador en fintable.io — las mismas cookies que usa tu navegador cuando tienes la sesión iniciada.

Orden de resolución de cookies:

  1. Almacén de cookies persistido — Si --persist-cookies está activo y ~/.fintable-mcp-cookies.json existe con cookies frescas, se usan esas. Se autoactualiza desde los encabezados Set-Cookie del servidor.
  2. rookiepy — Si está instalado, las cookies se extraen frescas de la base de datos local de Chrome en cada inicio del servidor. Cero mantenimiento.
  3. Variable de entorno FINTABLE_COOKIES — Cadena de cookies completa de Chrome DevTools (alternativa si rookiepy no está instalado).
  4. Variable de entorno FINTABLE_SESSION_COOKIE — Solo el valor de la cookie de sesión (opción manual más simple).

Cuando --persist-cookies está activo, cualquier método que proporcione las cookies iniciales también sembrará el almacén. En ejecuciones posteriores, el almacén tiene prioridad — y cada respuesta del servidor lo refresca automáticamente.

Este servidor nunca almacena tus credenciales en disco — solo viven en memoria mientras el servidor está en ejecución.

Expiración de sesión

Si usas rookiepy (recomendado), la expiración de sesión se maneja automáticamente — se extraen cookies frescas de Chrome en cada inicio del servidor. Solo asegúrate de mantener la sesión iniciada en fintable.io en Chrome.

Si usas exportación manual de cookies, tus cookies eventualmente expirarán. Cuando eso ocurra, el servidor devolverá un error de autenticación. Vuelve a exportar tus cookies desde Chrome y actualiza la variable de entorno FINTABLE_COOKIES.

Cómo funciona (para curiosos / desarrolladores)

Fintable.io es una aplicación Laravel que usa Livewire 3 + Alpine.js para su frontend — no hay una API REST pública. Este servidor MCP:

  1. Se autentica usando las cookies de sesión de tu navegador (token CSRF + cookie de sesión)
  2. Obtiene páginas para extraer instantáneas de componentes Livewire de los atributos HTML wire:snapshot
  3. Realiza llamadas al protocolo Livewire — solicitudes POST al endpoint /livewire-{hash}/update con instantáneas de componentes, llamadas a métodos y actualizaciones de propiedades
  4. Analiza las respuestas HTML para extraer datos estructurados (cuentas, categorías, reglas, transacciones)

La ruta de actualización de Livewire incluye un hash (p. ej., /livewire-5c7ce5a8/update) que puede cambiar cuando la aplicación se redespliega. El servidor descubre automáticamente esta ruta desde el atributo HTML data-update-uri en cada carga de página, por lo que se mantiene resistente entre despliegues.

Problemas y limitaciones conocidos

Cambios de hash de Livewire

El endpoint de actualización de Livewire incluye un hash de compilación (p. ej., /livewire-5c7ce5a8/update) que cambia en cada despliegue. El servidor lo descubre automáticamente en cada obtención de página, pero si Fintable reestructura significativamente sus componentes Livewire o cambia los nombres de los componentes, las cosas pueden romperse. Esto es inherente a trabajar sin una API oficial.

Fragilidad del análisis HTML

Como no hay una API JSON, las operaciones de lectura dependen del análisis de la estructura HTML. Si Fintable rediseña su interfaz, la lógica de análisis puede necesitar actualizarse. Esta es la mayor carga de mantenimiento del enfoque actual.

El camino a seguir: endpoints JSON

La solución ideal es que Fintable exponga endpoints JSON ligeros. Esto:

  • Eliminaría el frágil análisis HTML
  • Eliminaría la dependencia del hash de Livewire
  • Permitiría integraciones más fiables
  • Abriría la puerta a otras herramientas e integraciones comunitarias
  • Sería un gran argumento de venta para el producto (¡las herramientas financieras listas para MCP son un diferenciador!)

Si eres el desarrollador de Fintable y estás leyendo esto — incluso un puñado de endpoints JSON autenticados para categorías, reglas y transacciones haría que este servidor fuera sólido como una roca y dramáticamente más fácil de mantener. Feliz de colaborar en el diseño. 🚀

Modelo de seguridad

Este servidor se ejecuta localmente en tu máquina como un subproceso stdio de tu cliente MCP.:

  • Nunca expone un puerto de red
  • Nunca almacena credenciales en disco
  • Solo se comunica con fintable.io usando tu sesión de navegador existente
  • Se ejecuta como un proceso de un solo usuario y un solo cliente

Por defecto, las cookies de sesión se mantienen solo en memoria mientras el servidor está en ejecución. Con rookiepy, se extraen frescas de Chrome en cada inicio — sin variables de entorno ni archivos de configuración necesarios.

Si --persist-cookies está habilitado, las cookies se guardan en ~/.fintable-mcp-cookies.json (un dotfile en tu directorio personal). Esta es una compensación opcional: la conveniencia de una sesión auto-refrescante a cambio de cookies existiendo en disco. Elimina el archivo en cualquier momento para revocar la sesión.

Contribuciones

¡Las pull requests son bienvenidas! Algunas ideas para mejoras futuras:

  • Soporte para filtrado por rango de fechas en transacciones
  • Gestión de grupos de categorías (crear/renombrar grupos)
  • Reordenación de prioridad de reglas
  • Exportar categorías/reglas como JSON para copias de seguridad
  • Soporte para múltiples cuentas de Fintable

Nota sobre eliminaciones: La eliminación de categorías no está soportada intencionalmente — es una acción destructiva que se realiza mejor a través de la interfaz web de Fintable donde se puede ver el impacto completo. Un poco de fricción antes de eliminar cosas es una característica, no un error.

Aviso legal

Este proyecto no está afiliado, respaldado ni soportado oficialmente por fintable.io. Fue construido mediante ingeniería inversa del protocolo frontend de Livewire 3. Úsalo bajo tu propio riesgo — el protocolo Livewire subyacente puede cambiar sin previo aviso.

Licencia

MIT - Jason C Braatz