# Beancount MCP: Conecta tu libro mayor a asistentes de IA

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.

![Una computadora portátil de arcilla conectada a un libro mayor verde abierto, con un recibo en una bandeja de revisión y bloques enlazados que representan el historial de Git.](/img/blog/beancount-mcp/hero.webp)

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:

```text
https://beancount.io/api-gateway/mcp
```

### Claude Code

Añade el servidor desde tu terminal:

```bash
claude mcp add --transport http beancount https://beancount.io/api-gateway/mcp
```

Abre 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](https://code.claude.com/docs/en/mcp) 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](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

### Cursor

Añade el servidor a tu `~/.cursor/mcp.json` personal:

```json
{
  "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](https://cursor.com/docs/mcp) 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](https://beancount.io/settings/api-keys). **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:Cash` y categorizada bajo `Expenses:Food`. Verifica que esas cuentas existan y busca una transacción coincidente primero. Usa `appendLedgerText` con `dry_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í:

```beancount
2026-09-15 * "Café" "Café"
  Expenses:Food   4.50 USD
  Assets:Cash    -4.50 USD
```

Usa nombres de cuenta de tu propio libro mayor y luego completa la revisión:

1. Verifica la fecha, el monto, las cuentas y el archivo de destino en la previsualización.
2. Confirma el cambio exacto que quieres que aplique el asistente.
3. Pídele que ejecute `checkLedger` e informe el commit resultante y cualquier error.

`appendLedgerText` rechaza nuevos errores de validación por defecto. Los cambios generales de archivos usan `createLedgerFiles`, `updateLedgerFiles` y `deleteLedgerFiles`, que guardan sus archivos en un solo commit de Git cada uno. 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.
