Pregúntale a tu asistente de IA cuánto gastaste el mes pasado, qué cuentas necesitan conciliación o a dónde pertenece una transacción. Beancount MCP le da acceso a las consultas, cuentas y archivos fuente de tu libro mayor alojado, para que pueda trabajar con tus registros y mostrar la evidencia detrás de su respuesta.
Con permiso de escritura, el asistente también puede añadir transacciones y actualizar archivos del libro mayor. Puedes pedirle que previsualice ediciones compatibles, revise las entradas propuestas y verifique el libro mayor después de un cambio.
MCP significa Model Context Protocol: un estándar para conectar aplicaciones de IA a herramientas y datos externos. Esta conexión funciona con libros mayores alojados en Beancount.io. Las respuestas de tu asistente reflejan las transacciones y precios registrados allí; conectar MCP no hace que esos registros estén actualizados automáticamente.
Conecta tu cliente de IA
Usa un cliente que admita MCP remoto sobre Streamable HTTP. La URL del servidor es:
https://beancount.io/api-gateway/mcpClaude Code
Añade el servidor desde tu terminal:
claude mcp add --transport http beancount https://beancount.io/api-gateway/mcpAbre Claude Code, ejecuta /mcp, selecciona beancount y sigue su flujo de autenticación. Inicia sesión en Beancount.io y revisa los permisos solicitados. Vuelve a /mcp para confirmar la conexión. Consulta las instrucciones de MCP de Claude Code para detalles específicos del cliente.
La página de consentimiento te permite restringir el acceso a un libro mayor o elegir explícitamente Todos los libros mayores accesibles. Una restricción de un solo libro mayor es un punto de partida útil. Con acceso más amplio, indica al asistente qué libro mayor usar, como alice/personal; las herramientas del libro mayor deben identificar su objetivo en cada llamada.
Claude Desktop y Claude en la web
Abre Personalizar → Conectores, elige Añadir conector personalizado, ingresa la URL del servidor y conecta tu cuenta de Beancount.io. Habilita el conector para la conversación donde quieras usarlo. Las cuentas de organización pueden necesitar que un propietario añada el conector primero. Sigue la guía de conectores remotos de Claude.
Cursor
Añade el servidor a tu ~/.cursor/mcp.json personal:
{
"mcpServers": {
"beancount": {
"url": "https://beancount.io/api-gateway/mcp"
}
}
}Completa el inicio de sesión OAuth cuando Cursor lo solicite y luego verifica que las herramientas del servidor estén disponibles. La documentación de MCP de Cursor cubre la configuración y los ajustes de aprobación de herramientas.
Claves API personales
Para un cliente que acepte credenciales de portador, puedes crear una clave API personal en Configuración → Tokens de acceso personal. Crear una clave requiere un plan de pago de Beancount.io. Selecciona ledger.read para consultas, opcionalmente restringe la clave a un libro mayor y cópiala cuando se muestre. Configura el encabezado de autorización de tu cliente como Authorization: Bearer TU_CLAVE usando su configuración de credenciales privadas.
Mantén la clave fuera de la configuración compartida del proyecto. Los clientes OAuth gestionan las credenciales a través de su flujo de inicio de sesión; no necesitas crear una clave personal para esa ruta.
Comienza con una pregunta de gastos
Prueba esto después de conectar, reemplazando el nombre del libro mayor por el tuyo:
Usa
alice/personal. Identifica sus cuentas y monedas, luego resume los gastos de agosto de 2026 por cuenta. Muestra el rango de fechas y la BQL detrás de cada total, mantén las monedas separadas e informa cualquier error de validación del libro mayor. No cambies nada.
El asistente puede descubrir tus libros mayores con listLedgers, conocer los nombres de tus cuentas a través de getLedgerContext y ejecutar runBqlQueryStructured para resultados de consultas tipados. checkLedger devuelve errores de validación, recuentos de entradas y el último commit.
Una respuesta útil incluye el libro mayor, período, monedas, totales y consultas de respaldo. Para una pregunta de patrimonio neto, también pide el método de valoración y las fechas de los precios utilizados. Las transacciones faltantes o los precios desactualizados pueden cambiar la respuesta incluso si el libro mayor pasa la validación.
Añade una transacción con previsualización
Para nuevas entradas, appendLedgerText acepta texto ordinario de Beancount y enruta directivas a archivos usando la configuración de tu libro mayor. Su opción dry_run devuelve un diff y errores de validación proyectados antes de confirmar.
Por ejemplo:
Prepara una compra de café por 4.50 USD con fecha 15 de septiembre de 2026, pagada desde
Assets:Cashy categorizada bajoExpenses:Food. Verifica que esas cuentas existan y busca una transacción coincidente primero. UsaappendLedgerTextcondry_run: true, muestra la entrada propuesta y el diff del archivo, y espera mi confirmación.
Con esas cuentas ya abiertas, la entrada propuesta se vería así:
2026-09-15 * "Café" "Café"
Expenses:Food 4.50 USD
Assets:Cash -4.50 USDUsa nombres de cuenta de tu propio libro mayor y luego completa la revisión:
- Verifica la fecha, el monto, las cuentas y el archivo de destino en la previsualización.
- Confirma el cambio exacto que quieres que aplique el asistente.
- Pídele que ejecute
checkLedgere informe el commit resultante y cualquier error.
appendLedgerText rechaza nuevos errores de validación por defecto. Los cambios generales de archivos usan editLedgerFiles, que puede crear, reemplazar, actualizar o eliminar archivos en un solo commit de Git. Su previsualización también informa un diff y errores proyectados. Verifica el resultado y ejecuta checkLedger después de escribir: un commit exitoso aún puede contener errores contables.
Usa un flujo de trabajo para contabilidad recurrente
El servidor también proporciona avisos de MCP reutilizables. Los clientes con soporte de avisos los exponen en su selector de comandos o avisos:
| Flujo de trabajo | Para qué te ayuda |
|---|---|
spending-report | Responde una pregunta de gastos con BQL de respaldo y sin escrituras en el libro mayor. |
reconcile-account | Compara una cuenta con un estado de cuenta proporcionado, clasifica diferencias y propone entradas faltantes. |
close-month | Revisa cuentas activas, aserciones de saldo, transacciones recurrentes y banderas sin resolver. |
categorize-imports | Revisa transacciones bancarias en etapa de preparación y propone categorías usando cuentas existentes. |
Estos avisos guían al asistente a través de un procedimiento. No ejecutan un trabajo contable solo porque los selecciones, y no otorgan permisos adicionales.
La conciliación necesita un estado de cuenta y un saldo final. Un resultado limpio de validación por sí solo no puede establecer que cada transacción haya sido registrada. Pide al asistente que identifique cualquier cosa que no pudo verificar y deja esas preguntas visibles en el informe.
Para importaciones bancarias, primero vincula el banco en Beancount.io. Leer los detalles de conexión requiere acceso administrativo; enviar transacciones en etapa de preparación requiere permiso de escritura y el acceso apropiado a esa conexión bancaria. Revisa las categorías y duplicados propuestos antes de autorizar el envío.
Comprende el acceso y el manejo de datos
Los permisos de la conexión determinan lo que el asistente puede hacer:
| Permiso | Acceso |
|---|---|
ledger.read | Consultar y leer datos del libro mayor. |
ledger.write | Leer datos y hacer cambios ordinarios en el libro mayor. |
ledger.admin | Leer, escribir y realizar operaciones administrativas donde esté autorizado. |
Tu acceso existente a cada libro mayor sigue aplicándose. Restringir una credencial a un solo libro mayor impide que las llamadas apunten a otro; una credencial sin restricciones puede seleccionar entre los libros mayores a los que puedes acceder. El cliente OAuth elige qué permisos solicitar, así que lee la pantalla de consentimiento antes de aprobar.
El servidor MCP no muestra un diálogo de aprobación humano. La configuración de tu cliente determina cuándo pregunta antes de llamar a una herramienta, y las previsualizaciones deben solicitarse explícitamente. Los flujos de trabajo de escritura suministrados instruyen al asistente a esperar confirmación. Una credencial restringida a ledger.read proporciona un límite forzado cuando quieres análisis sin escrituras.
Los resultados de las herramientas, incluidas las transacciones consultadas y los archivos que el asistente lee, entran en el contexto de tu cliente de IA y pueden ser procesados por su proveedor de modelos. Beancount.io retiene tu libro mayor, historial de Git y registros operativos. Una conexión MCP sin estado no es una promesa de que no se retienen datos; las políticas de datos de tu cliente y proveedor también se aplican.
Las claves API personales revocadas se rechazan en solicitudes posteriores. Los tokens de acceso OAuth normalmente duran una hora; revocar un token de actualización no invalida inmediatamente un token de acceso ya emitido. El acceso al libro mayor se vuelve a verificar cuando se ejecutan operaciones protegidas.
Preguntas comunes
¿Esto abre el libro mayor en mi computadora portátil?
El endpoint alojado opera en tu libro mayor de Beancount.io. No abre un archivo .bean local y no necesitas una pestaña del navegador con Fava abierta.
¿En qué se diferencia del asistente de IA del panel de control?
El panel proporciona su propia interfaz de chat. MCP hace que las capacidades del libro mayor estén disponibles desde un cliente de IA externo, con la conversación, el modelo y los ajustes de aprobación de ese cliente.
¿Por qué puedo ver una herramienta pero no usarla?
El catálogo de herramientas incluye operaciones que tu credencial puede no permitir. Verifica el error y los permisos otorgados. Una credencial sin restricciones también necesita un objetivo de libro mayor explícito para las herramientas del libro mayor.
Conecta tu libro mayor y comienza con una pregunta que puedas verificar contra tus registros. Guarda la consulta con la respuesta y luego añade permisos de escritura cuando quieras ayuda para mantener el libro mayor mismo.
