bookie

Servidor MCP de contabilidad por partida doble: importa CSV bancarios, categoriza, concilia y genera informes fiscales.

Documentación

bookie

Un servidor MCP que lleva la contabilidad para autónomos y propietarios de alquileres — controlado desde Claude o GPT en lugar de QuickBooks.

Pídele a tu LLM que importe un extracto bancario, categorice gastos, concilie un mes o genere un Anexo C. Bookie proporciona el libro mayor de partida doble correcto debajo — para que el modelo razone sobre números reales, no sobre una hoja de cálculo que improvisa sobre la marcha.

Esto es para ti si: eres un emprendedor individual, autónomo o propietario de propiedades en alquiler que ya vive en Claude o GPT, te sientes cómodo con una configuración de 5 minutos y quieres libros que sean realmente correctos.

No es para ti si: quieres una interfaz de panel, necesitas acceso multiusuario o estás satisfecho con QuickBooks / una hoja de cálculo.

Lo que necesitas antes de empezar

Node ≥ 24
neonctl — npm install -g neonctl (cuenta gratuita de Neon; necesaria para la base de datos)
Un host compatible con MCP: Claude Desktop, Claude.ai, Cursor, VS Code o cualquier host que admita el transporte stdio o HTTP de MCP

Inicio rápido (local, stdio)

Recomendado — desde el código fuente, totalmente automatizado:

git clone https://github.com/yuens1002/bookie
cd bookie
npm install
npm run setup   # creates Neon DB, generates secrets, writes .env, runs db:push
npm run build

npm run setup abre un navegador para iniciar sesión en Neon; ¿nuevo en Neon? Usa el enlace "Regístrate para obtener una cuenta" y elige GitHub/Google/Microsoft en lugar de correo electrónico+contraseña — se completa en el mismo viaje de ida y vuelta del navegador, sin desvío de verificación por correo electrónico que podría interrumpir la CLI a mitad de espera.

npm run setup imprime un bloque de configuración de Claude Desktop listo para pegar al final:

{
  "mcpServers": {
    "bookie": {
      "command": "node",
      "args": ["/absolute/path/to/bookie/dist/index.js"],
      "env": {
        "BOOKIE_DB_URL": "<printed by setup>",
        "BOOKIE_DB_DIRECT_URL": "<printed by setup>",
        "BOOKIE_API_KEY": "<printed by setup>"
      }
    }
  }
}

Añadir otra máquina al mismo libro mayor — sin necesidad de clonar: stdio es un proceso local — cada máquina que ejecuta un cliente MCP stdio genera su propia copia del servidor, por lo que cada una necesitaría su propio checkout. Una vez que la base de datos de Neon está aprovisionada (mediante npm run setup arriba, en cualquier máquina), cada otra máquina solo necesita las mismas cadenas de conexión — sin git clone, sin npm install, sin npm run build que mantener sincronizados. Apunta el host MCP de esa máquina al paquete publicado en su lugar:

{
  "mcpServers": {
    "bookie": {
      "command": "npx",
      "args": ["-y", "bookie-mcp"],
      "env": {
        "BOOKIE_DB_URL": "<same value as your first machine>",
        "BOOKIE_DB_DIRECT_URL": "<same value as your first machine>",
        "BOOKIE_API_KEY": "<same value as your first machine>"
      }
    }
  }
}

npx obtiene y ejecuta la versión publicada bajo demanda — cada máquina apuntada al mismo BOOKIE_DB_URL comparte un libro mayor, sin que ninguna de ellas (además de la original) necesite un checkout.

Inicializar una base de datos sin clonar en absoluto: si aún no tienes cadenas de conexión de ninguna máquina (por ejemplo, creaste el proyecto de Neon manualmente en lugar de mediante npm run setup), envía el esquema incluido de bookie directamente:

mkdir bookie-mcp && cd bookie-mcp
npm install bookie-mcp
BOOKIE_DB_URL=<pooled> BOOKIE_DB_DIRECT_URL=<direct> npx prisma db push --schema=node_modules/bookie-mcp/prisma/schema.prisma

Luego usa la misma configuración de npx -y bookie-mcp de arriba.

Inicio rápido (remoto, HTTP — para Claude.ai móvil)

Despliega en Railway con un clic:

Railway extrae la imagen preconstruida de GHCR — no se necesita compilación desde el código fuente. Establece las variables de entorno requeridas cuando se te solicite. Consulta docs/DEPLOYING.md para el tutorial completo (referencia de variables de entorno, configuración de Neon + Resend, conector OAuth de Claude.ai).

¿Por qué sin interfaz de usuario?

El LLM anfitrión ya lee archivos CSV, ve imágenes de recibos y escribe prosa. Bookie posee las cosas que un LLM no debería improvisar: un libro mayor de partida doble correcto, matemática monetaria en centavos enteros, reglas de categorización deterministas e informes reproducibles. El modelo maneja el lenguaje y la visión; el servidor maneja los libros.

Herramientas

La referencia completa y siempre actual de herramientas vive en docs/TOOLS.md (regenerar con npm run docs:tools). Hoy:

Herramienta	Qué hace
`manage_accounts`	Crear/listar/archivar cuentas (las categorías con ámbito de segmento llevan una línea fiscal)
`add_transaction`	Registrar una entrada de partida doble equilibrada (el dinero fluye de → a)
`split_transaction`	Una pata de pago + N patas de categoría (un recibo dividido entre categorías)
`import_transactions`	Importar un CSV bancario/de tarjeta como entradas equilibradas — previsualizar → confirmar, con deduplicación
`manage_rules`	Crear/listar/eliminar/probar/sugerir reglas de auto-categorización (categorizar → cuenta/propiedad, o excluir) que alimentan las sugerencias de previsualización de importación; `action=suggest` escanea categorizaciones pasadas y devuelve reglas candidatas para descripciones con 2+ ocurrencias
`categorize_transaction`	Re-categorizar la pata de ingresos/gastos de una entrada existente — cuenta explícita o aplicar una regla almacenada
`reconcile`	Comparar un CSV de extracto bancario/de tarjeta contra el libro mayor y marcar los asientos como compensados — previsualizar y luego confirmar
`manage_receipts`	Adjuntar, listar, eliminar u obtener una URL de descarga firmada para datos de recibos; opcionalmente subir el archivo original (JPEG, PNG, WEBP, HEIC o PDF) al almacenamiento Railway Bucket
`generate_report`	Resumen de conciliación mensual, o Anexo C / Anexo E de pérdidas y ganancias fiscales del año fiscal
`export_report`	Renderizar cualquier informe como markdown o CSV
`send_report`	Ejecutar un informe y enviarlo por correo electrónico mediante Resend
`query_transactions`	Listar entradas + asientos por rango de fechas / cuenta
`account_balances`	Saldo actual por cuenta

Recursos

Bookie expone dos recursos MCP que un LLM puede leer sin llamar a una herramienta:

URI del recurso	Tipo MIME	Qué contiene
`bookie://accounts`	`application/json`	Todas las cuentas activas con sus saldos actuales
`bookie://reports/{year}`	`text/markdown`	Instantánea fiscal anual: Anexo C, Anexo E y un resumen de una fila por mes (saldo inicial, ingreso neto, recuento de asientos compensados)

Prompts

Tres prompts de flujo de trabajo predefinidos guían al LLM a través de tareas contables comunes:

Prompt	Parámetros	Propósito
`monthly-close`	`year`, `month`	Cierre de fin de mes paso a paso: importar CSV → categorizar → conciliar → informar → (opcional) enviar por correo electrónico
`categorize-uncategorized`	(ninguno)	Encontrar asientos de diario sin pata de ingresos/gastos y recorrer la categorización de cada uno
`prepare-tax-summary`	`year`	Generar Anexo C + E, exportar como markdown y CSV, opcionalmente enviar por correo electrónico

Configuración

Consulta .env.example para la referencia completa. Variables clave:

Variable	Propósito
`BOOKIE_TRANSPORT`	`stdio` (predeterminado) o `http`
`BOOKIE_DB_URL`	Cadena de conexión agrupada de Neon
`BOOKIE_DB_DIRECT_URL`	Cadena de conexión directa de Neon (para `db push`)
`BOOKIE_API_KEY`	Token Bearer estático (Claude Desktop / API directa)
`PUBLIC_URL`	URL base HTTPS pública del servidor desplegado (conector Claude.ai)
`JWT_SECRET`	Secreto de firma HS256 para tokens de acceso JWT OAuth
`OAUTH_CLIENT_ID`	ID de cliente OAuth (predeterminado: `claude-ai-connector`)
`OAUTH_CLIENT_SECRET`	Requerido al usar OAuth: `/authorize` rechaza todas las solicitudes cuando no está establecido (evita que cualquier visitante autorice); `/token` también lo valida. Ingresa este valor en la configuración del conector de Claude.ai.
`RESEND_API_KEY`	Clave API de Resend para `send_report`
`RESEND_FROM`	Dirección de remitente verificada para `send_report` (por ejemplo, `Bookie <reports@yourdomain.com>`)
`AWS_ENDPOINT_URL` / `AWS_S3_BUCKET_NAME` / `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_DEFAULT_REGION`	Credenciales de Railway Bucket — inyectadas automáticamente cuando conectas un bucket al servicio (usa estilo AWS SDK Generic); habilita la subida de archivos de recibos en `manage_receipts`

Documentación

Arquitectura — modelo de datos, transportes, capas
Despliegue — configuración de Railway + Neon + Resend
Hoja de ruta — plan por fases
Registro de cambios — lo que se ha lanzado
Publicación — versionado + proceso de lanzamiento
Herramientas — manual generado
Contribución — configuración, convenciones, pruebas

Seguridad

Bookie almacena datos financieros en tu base de datos Postgres de Neon; las cadenas de conexión viven en .env (ignorado por git) y en variables de entorno de Railway — nunca las confirmes. El transporte HTTP requiere autenticación en cada solicitud de /mcp: ya sea un token Bearer estático (BOOKIE_API_KEY) o un JWT OAuth emitido por el endpoint de /token. Siempre establece al menos uno antes de exponer el servidor más allá de localhost. Consulta docs/DEPLOYING.md para la configuración completa del conector OAuth de Claude.ai.

Licencia

MIT