Beancount MCP: conecta tu libro contable a Claude, Cursor y cualquier asistente de IA

Web Beancount lanza un servidor MCP — habla con tu libro contable desde Claude, Cursor y cualquier herramienta de IA que ya uses

Tus datos contables se encuentran con tu flujo de trabajo de IA. Sin copiar y pegar. Sin exportaciones. Solo pregunta.

Hoy, Web Beancount anuncia el servidor Beancount MCP — un endpoint de Model Context Protocol (MCP) que te permite conectar tu libro contable de Beancount directamente a Claude Desktop, Claude Code, Cursor, Windsurf o cualquier otro cliente de IA compatible con MCP. Por primera vez, los usuarios avanzados pueden hacer preguntas contables, ejecutar consultas BQL e incluso editar archivos del libro contable desde dentro de las herramientas de IA en las que ya viven — sin cambiar de pestaña ni salir de su flujo de trabajo.

Los archivos de Beancount en texto plano son potentes precisamente porque no son más que archivos. Pero responder "¿cuánto gasté en viajes el trimestre pasado?" todavía requiere conocer la sintaxis de BQL, saber dónde están tus archivos y copiar los resultados a un chat. El servidor Beancount MCP elimina esa fricción por completo.

Con el servidor Beancount MCP configurado en tu cliente de IA, puedes:

Preguntar "¿Cuál es mi patrimonio neto hoy?" y obtener una respuesta en vivo extraída de tu libro contable real
Solicitar un resumen de los gastos del mes pasado y dejar que la IA escriba la consulta BQL por ti
Decirle a la IA que añada una transacción y ver cómo confirma el cambio en el repositorio git de tu libro contable
Explorar y leer tus archivos .beancount sin salir nunca de tu editor

El servidor está delimitado por libro contable: cada sesión de MCP está autorizada para exactamente un libro contable mediante OAuth 2.1. Clientes como Claude Code descubren y completan el flujo de autorización automáticamente — no se requiere gestión manual de tokens. Tu libro contable permanece donde ya vive, en el backend de Web Beancount: el cliente de IA envía llamadas de herramientas estructuradas a nuestro servidor, que lee o edita tu libro contable en tu nombre y devuelve los resultados. El propio servidor MCP no almacena nada más allá de lo que contiene la conversación de tu cliente de IA.

El servidor Beancount MCP está disponible hoy para todos los usuarios de Web Beancount.

Empezar

El servidor Beancount MCP está activo. Añádelo a tu cliente de IA en menos de un minuto.

URL del servidor MCP

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

Claude Code (recomendado — flujo completo de OAuth 2.1, sin necesidad de token)

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

En el primer uso, Claude Code abrirá una ventana del navegador. La solicitud del navegador es donde eliges qué libro contable conectar — aprueba una vez y las credenciales se actualizan automáticamente. ¿Tienes más de un libro contable? Añade el servidor de nuevo con un nombre diferente (claude mcp add --transport http beancount-business https://beancount.io/api-gateway/mcp) y autoriza el otro libro contable en su propia solicitud.

Claude Desktop / Cursor / Windsurf / Zed

Añade el servidor a la configuración MCP de tu cliente (claude_desktop_config.json o equivalente). Los clientes con soporte de OAuth 2.1 abren la misma solicitud del navegador en el primer uso — elige tu libro contable ahí:

{
  "mcpServers": {
    "beancount": {
      "url": "https://beancount.io/api-gateway/mcp"
    }
  }
}

Si tu cliente aún no admite el flujo de OAuth, genera un token estático (delimitado a un solo libro contable) desde la configuración de tu cuenta de beancount.io y pásalo como cabecera:

{
  "mcpServers": {
    "beancount": {
      "url": "https://beancount.io/api-gateway/mcp",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}

¿No tienes una cuenta de Web Beancount? Regístrate en beancount.io — tu libro contable está a un git push de distancia.

Preguntas frecuentes

Preguntas frecuentes de clientes

¿Qué es MCP y por qué importa para Beancount?

MCP (Model Context Protocol) es un estándar abierto que permite a los asistentes de IA llamar a herramientas y fuentes de datos externas de forma estructurada y segura. Piénsalo como un puerto USB para la IA: en lugar de que la IA adivine o te pida que pegues datos, se conecta directamente a tus sistemas. Para los usuarios de Beancount, esto significa que tu cliente de IA puede consultar los datos reales de tu libro contable, leer tus archivos reales y hacer ediciones precisas — no adivinar lo que podrían contener.

¿Qué clientes de IA funcionan con el servidor Beancount MCP?

Cualquier cliente compatible con MCP que admita OAuth 2.1 funciona de forma inmediata. El servidor Beancount MCP implementa el flujo completo de autorización de OAuth 2.1 con PKCE, así que clientes como Claude Code descubrirán automáticamente el endpoint de autorización del servidor y te pedirán que inicies sesión — sin copiar tokens ni configurar nada manualmente. Una vez que apruebas el acceso, el cliente almacena y actualiza las credenciales automáticamente.

Entre los clientes con soporte conocido de MCP + OAuth 2.1 se incluyen Claude Code CLI, Claude Desktop, Cursor, Windsurf y Zed. A medida que crece el ecosistema de MCP, cualquier cliente nuevo que siga la especificación MCP de OAuth 2.1 funcionará sin cambios por nuestra parte.

¿Cómo conecto mi libro contable?

Para clientes que admiten OAuth 2.1 (como Claude Code):

Añade la URL del servidor Beancount MCP a la configuración MCP de tu cliente.
El cliente abre automáticamente una ventana del navegador para autorizar el acceso.
Inicia sesión con tu cuenta de Web Beancount y elige el libro contable al que quieres conceder acceso.
Listo — el cliente se encarga del almacenamiento y la actualización del token a partir de aquí.

Para clientes sin soporte de OAuth 2.1, genera un token estático (delimitado a un solo libro contable) desde la configuración de tu cuenta de Web Beancount y pásalo como una cabecera Authorization: Bearer.

¿Es lo mismo que la función de chat "Ask AI" del panel de control?

Comparten las mismas herramientas subyacentes del libro contable (consultas BQL, lectura/escritura de archivos), pero el servidor MCP es un punto de entrada diferente. La función Ask AI del panel es una experiencia de chat alojada con un sandbox de Claude Code respaldado por Cloudflare. El servidor MCP es un endpoint de protocolo al que te conectas desde tu propio cliente de IA preferido — lo que te da más control, más modelos y una integración más profunda con tu flujo de trabajo existente.

¿Qué puede hacer realmente la IA con mi libro contable?

El servidor MCP expone cuatro herramientas:

Herramienta	Qué hace
`runBqlQuery`	Ejecuta BQL (Beancount Query Language) para consultar saldos, transacciones y cuentas
`listLedgerFiles`	Explora la estructura de directorios del repositorio de tu libro contable
`readLedgerFiles`	Lee el contenido de los archivos `.beancount` y otros documentos del libro contable
`editLedgerFiles`	Crea, actualiza, reemplaza o elimina archivos en un commit atómico de git

La IA puede combinarlas: descubrir la estructura de tus archivos, leer los archivos relevantes para obtener contexto, escribir una consulta BQL para responder tu pregunta, o proponer y confirmar una edición.

¿Puede la IA modificar mi libro contable sin que yo lo sepa?

Las ediciones de archivos requieren que el cliente de IA llame a editLedgerFiles con una descripción de lo que está cambiando. Los clientes MCP que se comportan correctamente (incluido Claude Code) te lo muestran antes de ejecutarlo. Las ediciones también admiten un modo dry_run que previsualiza los cambios exactos sin escribir nada, de modo que tu cliente puede mostrarte primero un diff. Y cada cambio confirmado es un commit de git real en el repositorio de tu libro contable, así que tienes un registro de auditoría completo y puedes revertir cualquier cosa con las herramientas estándar de git.

¿Se envían mis datos a un tercero?

Los datos de tu libro contable fluyen a través del backend de Web Beancount (que ya gestiona tu libro contable) y se devuelven como resultados estructurados a tu cliente de IA. El modelo de IA que uses (por ejemplo, Claude) recibe los resultados de las herramientas como cualquier otro contexto. El servidor MCP no almacena ningún dato más allá de lo que ya contiene la conversación de tu cliente de IA.

Cada token está delimitado por libro contable — ¿qué significa eso?

Cuando autorizas el servidor MCP, eliges a qué libro contable conceder acceso. Esa sesión solo puede acceder a ese libro contable. Si tienes varios libros contables, autorizas sesiones separadas. Esto limita el radio de impacto: una sesión para tu libro contable personal no puede tocar tu libro contable de empresa.

¿Requiere el servidor MCP que la interfaz web de Fava esté en ejecución?

No. El servidor MCP se comunica con la API interna de Fava gestionada por la infraestructura de Web Beancount (Fava es la interfaz web que impulsa tu libro contable de beancount.io). No necesitas tener la interfaz de Fava abierta ni accesible.

¿Qué pasa si revoco mi acceso a MCP?

Las sesiones de MCP en curso recibirán errores 401 en la siguiente llamada de herramienta. Los clientes que admiten OAuth 2.1 intentarán reautorizarse automáticamente, pidiéndote que inicies sesión de nuevo.

Por dentro

Para los técnicamente curiosos — cómo está construido el servidor.

¿Por qué MCP en lugar de construir nuestra propia API/plugin para cada herramienta de IA?

MCP es el estándar emergente y ya es compatible con todos los principales editores de IA. Construir un servidor MCP conforme nos da compatibilidad con todo el ecosistema de una vez, frente a mantener integraciones separadas para Claude, Cursor, Windsurf y lo que salga el próximo trimestre. El protocolo se encarga del descubrimiento, los esquemas de herramientas y el streaming — nosotros nos centramos en la lógica del dominio.

¿Por qué OAuth 2.1 en lugar de claves de API estáticas?

OAuth 2.1 con PKCE es lo que recomienda la especificación de MCP para servidores remotos, y es lo que clientes como Claude Code implementan de forma nativa. El beneficio práctico: los usuarios nunca tocan un token. El cliente descubre el servidor de autorización a través de nuestro endpoint de metadatos .well-known/oauth-protected-resource, completa PKCE y gestiona la actualización automáticamente. Los tokens estáticos siguen siendo compatibles como alternativa para clientes que no han implementado el flujo completo.

¿Por qué Streamable HTTP en lugar de transporte SSE o stdio?

Streamable HTTP es el transporte de MCP diseñado para servidores remotos sobre HTTPS. Stdio es para procesos locales. SSE (el transporte de MCP más antiguo) se está descontinuando en favor de Streamable HTTP. Nuestros usuarios se conectan desde clientes de IA que no están ubicados junto a nuestro servidor, así que Streamable HTTP es la elección correcta y con visión de futuro.

¿Por qué la sesión de MCP es sin estado (sin sessionIdGenerator)?

Establecemos sessionIdGenerator: undefined para que cada solicitud sea completamente sin estado — no se asigna ni se retiene ningún estado de sesión del lado del servidor entre llamadas de herramientas. Esto coincide con el modo sin estado de la especificación de Streamable HTTP y mantiene el servidor escalable horizontalmente sin afinidad de sesión. El contexto de la herramienta (identidad del libro contable, cliente de la API de Fava) se reconstruye por solicitud a partir del token OIDC validado.

¿Cómo funciona la verificación del acceso al libro contable?

Tras la validación del token OIDC, resolveLedgerAccess comprueba a través de la API de Fava que el usuario autenticado realmente tiene acceso al libro contable solicitado. Esto evita que un token válido para un libro contable se use para sondear el libro contable de otro usuario (defensa en profundidad además del token firmado).

¿A dónde confirma editLedgerFiles?

Llama a changeLedgerFiles en la API de Fava, que crea un commit de git en el repositorio Gitea del libro contable con el mensaje AI edit: <description>. La descripción proviene del campo description que rellena la IA — mostrado al usuario en los clientes MCP que se comportan correctamente antes de ejecutar.

¿Qué es la opción dry_run en editLedgerFiles?

dry_run: true valida todas las operaciones de archivos (comprueba que los archivos existen, verifica que las cadenas antiguas de str_replace coinciden exactamente una vez) y devuelve una vista previa de lo que se confirmaría — sin escribir realmente en git. Esto es útil para los clientes de IA que quieren mostrar un diff al usuario antes de confirmar.

¿Cuál es la superficie de error visible para los clientes de IA?

Los errores de las herramientas se devuelven como { isError: true, content: [{ type: "text", text: "..." }] } — el formato de error estructurado del SDK de MCP. El cliente de IA recibe el mensaje de error como texto y puede decidir cómo manejarlo (reintentar, informar al usuario, etc.). Los fallos de autenticación a nivel de HTTP (401) incluyen una cabecera WWW-Authenticate que apunta a los metadatos del recurso protegido por OAuth, de modo que los clientes conformes pueden reiniciar automáticamente el flujo de autorización.