gnucash-mcp

gnucash-mcp

Software de contabilidad gratuito y de código abierto que funciona con el LLM.

Habla con tus libros de GnuCash a través de Claude (o cualquier asistente de IA que admita MCP). Pregunta "¿cómo voy este mes?", dicta tus transacciones en voz alta, entrega los libros para que la IA los mantenga al día mientras tú te concentras en dirigir tu vida o tu negocio.

El servidor se ejecuta en tu máquina y trabaja con tu archivo local de GnuCash; el archivo y su registro de auditoría nunca salen de ella. Tu asistente de IA ve lo que devuelven sus llamadas a herramientas (saldos, beneficiarios, facturas), tal como lo verías tú en pantalla.

¿Actualizando desde 1.4? Lee la guía de actualización antes de tu primera escritura con 1.5.

Instalación en un clic: en Claude Desktop, descarga el paquete .mcpb desde la última versión, haz doble clic y ya estás en marcha — sin terminal, sin archivos de configuración. Cualquier otro cliente MCP — ChatGPT/Codex, Gemini, Antigravity y el resto — se conecta con unas pocas líneas de configuración. De cualquier manera, la suscripción de IA que ya pagas se convierte en un contable que nunca envía una factura.

Tres libros de muestra realistas te permiten probarlo antes de comprometer nada: años completos de actividad, monedas mixtas, clientes, facturas y presupuestos. El paquete de Claude Desktop los incluye; desde un clon, un comando los crea. Recorre uno en cinco minutos; si te convence, apunta el servidor a tu propio libro y listo.

---

¿Cómo se ve?

Esto es lo que ve tu asistente de IA cuando abre uno de los libros de muestra — un panel financiero completo en una sola llamada:

Book: alex-chen-morales.gnucash
Currency: USD
Data range: 2025-01-01 to 2026-10-08
Last entry: 2026-10-08 (today)
Chart of accounts: 111 total (109 active) — drill into any branch with list_accounts(root="Assets:Investments"):
  Assets (25 total): Investments (9), Current Assets (5), Fixed Assets (3), Receivables (3), Retirement (3)
  Liabilities (8 total): Credit Card (3), Loans (3)
  Equity (3 total)
  Income (11 total): Investment Income (6)
  Expenses (64 total): Business (14), Taxes (10), Utilities (6), Auto (4), Housing (4), Interest (4), Insurance (3), Pet (3)
Assets: USD 874270.54
  Condo: USD 475000.00
  VTSAX: 453.4039 VTSAX @ 185.53 (USD 84120.03)
  UWRP 403(b): USD 74778.40
  Savings Account: USD 60000.00
  Cascade Code LLC Checking: USD 41390.64
  ...
Liabilities: USD 389695.79
  Credit cards (2): USD 1319.99
  Loans & other (2): USD 385873.30
  Top 3: Mortgage USD 373846.80, Auto Loan USD 12026.50, Chase Sapphire USD 876.31
Receivables: 2 accounts, USD 27324.47 (4 invoices, 0 overdue; included in Assets total)
  Accounts Receivable: USD 22425.00
  Accounts Receivable EUR: USD 4899.47
Payables: 1 account, USD 2502.50 (1 bill, 0 overdue; included in Liabilities total)
  Accounts Payable: USD 2502.50
Jobs: 3 active
Frequently used accounts (last 180 days — any account parameter accepts the %guid or the full name; a %guid is fewer tokens and faster to write):
  %528b7d9	Assets:Current Assets:Checking Account [BANK]
  %8799a0a	Liabilities:Credit Card:Chase Sapphire [CREDIT]
  %839fcf8	Expenses:Dining
  ...
Reconciliation:
  6 accounts current
Net worth trajectory:
  12mo ago: USD 345,969
   6mo ago: USD 381,961
   3mo ago: USD 429,392
   1mo ago: USD 443,546
       now: USD 484,575
Monthly net (income - expenses, last 6 months):
  Oct 2026 (MTD): +11,955 (vs Sep 1-8: -2,365)
  Sep 2026: +25,894
  Aug 2026: +7,588
  Jul 2026: +10,307
  Jun 2026: +24,092
  May 2026: +9,017
Runway: 579 days (USD 246,844 liquid / USD 426/day cash out incl. debt paydown, 180-day avg; cards owe USD 1,320)
Budget (2026 Annual Budget): USD 27,736 spent / USD 28,683 expected by today (-3%)
Transactions: 2227
Scheduled: 20 recurring, 16 due in next 7 days (USD 15,128 out)
Business: 8 customers, 3 vendors
Budgets: 2
Commodities: AAPL, CAD, ETH, EUR, MSFT, USD, VBTLX, VTSAX

Eso no es una captura de pantalla — es la vista de orientación real de la IA. Trayectoria del patrimonio neto, margen de maniobra, ritmo del presupuesto, quién te debe dinero, qué está vencido, qué no ha sido conciliado. Una llamada, y tu asistente tiene el panorama completo antes de que termines de saludar.

---

¿Para quién es esto?

• Personas de finanzas personales que llevan sus libros en GnuCash y quieren dictar transacciones, preguntar a su asistente a dónde va el dinero, obtener ayuda con la conciliación, planificar presupuestos.
• Dueños de pequeñas empresas que llevan sus libros en GnuCash y quieren emitir facturas, rastrear cuentas por cobrar, ver el gasto de proveedores, gestionar el flujo de caja sin salir de la conversación.
• Personas que se preocupan de que sus datos permanezcan locales. Sin sincronización en la nube. Sin SaaS. Tu archivo .gnucash es el sistema de registro; esto solo le da a tu IA una forma de leerlo y escribirlo de la misma manera que lo hace el propio GnuCash.

No necesitas ser desarrollador. Necesitas:

• Una computadora (Mac, Windows o Linux)
• GnuCash en sí, o disposición a instalarlo (gratis en gnucash.org)
• Un asistente de IA que admita MCP (Claude Desktop es el más común; Claude Code, Continue.dev y otros también funcionan)
• 10 minutos para poner en marcha los libros de muestra, y otros 10 para apuntar a los tuyos

---

Pruébalo sin arriesgar nada

El repositorio incluye tres personas de muestra — libros contables sintéticos con los que puedes hablar sin tocar tus datos reales. El paquete los trae completamente construidos; desde un clon, un comando los crea. Elige uno, apunta el servidor a él y empieza a hacer preguntas.

samples/alex-chen-morales.gnucash — Personal + freelance

Un contratista independiente de software con sede en Seattle con una LLC de un solo miembro y un cónyuge en nómina de un hospital. Moneda predeterminada USD. 111 cuentas y más de 2,000 transacciones desde 2025 hasta la fecha de creación. Tiene una hipoteca, una correduría con tenencias de VTSAX/VBTLX/AAPL/MSFT/ETH, un Solo 401(k) junto al 403(b) del cónyuge, ocho clientes facturados en USD, EUR y CAD, un subcontratista facturado a través de cuentas por pagar, impuesto B&O de Washington, facturas programadas, presupuestos — prácticamente todo lo que el servidor puede hacer, todo en un solo libro.

samples/lin-wei.gnucash — Estudio de software en Shenzhen

Un desarrollador de Shenzhen que dirige un estudio registrado como propietario único que crea software de comercio electrónico transfronterizo, con un cónyuge en nómina de un hospital. Moneda predeterminada CNY, en un plan de cuentas nativo zh_CN. 101 cuentas y alrededor de 3,000 transacciones. Clientes tecnológicos de Shenzhen (Tencent, DJI, SF Tech y otros) que pagan en CNY, clientes en USD/EUR que pagan en moneda extranjera con ganancias/pérdidas por diferencias de cambio realizadas en los movimientos de tipos, inversiones nacionales chinas (宁德时代 y dos ETFs), un empleado a tiempo parcial, una tarjeta de crédito en HKD, una hipoteca y canales de pago mixtos (cuenta corporativa + Alipay + WeChat Pay).

samples/sabine-brenner.gnucash — Freelancer alemán, plan de cuentas SKR03

Un diseñador freelance con sede en Múnich. Moneda predeterminada EUR, en un plan de cuentas alemán SKR03 — cada nombre de cuenta en alemán. 125 cuentas y alrededor de 1,900 transacciones, con declaraciones de IVA en vivo y un coche de empresa bajo la regla del 1%. Si una función asume nombres de cuenta en inglés o USD, el libro de Sabine es donde se rompe.

Los tres libros son ficticios. Consulta samples/README.md para el desglose completo de lo que contiene cada uno.

---

Inicio rápido

Instalación en un clic (Claude Desktop)

Descarga el paquete .mcpb desde la última versión y haz doble clic. Claude Desktop instala el servidor — sin terminal, sin archivo de configuración, sin Python. El instalador pregunta tres cosas:

• Tus libros de GnuCash — un selector de archivos. Los libros deben estar en formato SQLite; si el tuyo es el formato XML más antiguo, haz la conversión única primero. Elige varios libros para cambiar entre ellos en el chat.
• Libros de demostración — una casilla sirve los tres libros de muestra descritos arriba, para que puedas explorar con dinero ficticio antes (o en lugar de) conectar el tuyo.
• "¿Facturas a clientes?" — sí añade el conjunto empresarial (facturas de clientes, facturas de proveedores, gastos de empleados). Todo lo demás — presupuestos, transacciones programadas, seguimiento de inversiones — está siempre activado.

Esa es toda la instalación.

Pruébalo

Pregunta a Claude:

• "Resume el libro."
• "¿Cómo ha estado mi patrimonio neto?"
• "Muéstrame a cualquiera que me deba dinero."
• "¿En qué gasté en restaurantes el mes pasado?"
• "Establece un presupuesto mensual de comestibles de $500."

La primera respuesta suele comenzar con el panel de control de arriba. Todo lo demás después es conversacional.

Cuando estés listo para tu propio libro, consulta Conexión a tu propio libro abajo.

Otros clientes de IA, o instalación desde el código fuente

ChatGPT y Codex, Claude Code, Gemini CLI, Google Antigravity y cualquier otro cliente MCP se conectan mediante una instalación desde un clon de git, al igual que los libros de base de datos y cualquiera que trabaje en el servidor: consulta docs/CLIENTS.md.

---

Conexión a tu propio libro

Conversión única: formato de archivo de GnuCash

El servidor solo lee la forma SQLite de los archivos de GnuCash, no la forma XML más antigua. Para convertir:

1. Abre tu libro en el propio GnuCash
2. Archivo → Guardar como
3. Cambia "Formato de datos" a SQLite3
4. Guarda con un nombre de archivo nuevo (p. ej. mybook-sqlite.gnucash)
5. Conserva el XML original como copia de seguridad.

En Linux (Debian/Ubuntu), SQLite3 puede faltar por completo en el menú desplegable "Formato de datos" — GnuCash necesita un controlador de backend que no está instalado por defecto. Cierra GnuCash, instálalo y luego vuelve a abrirlo y la opción aparece:

sudo apt update && sudo apt install libdbd-sqlite3

Solo haces esto una vez. A partir de entonces, GnuCash y el servidor MCP trabajan ambos contra el mismo archivo SQLite.

GnuCash 3.8 o más reciente. Una vez que el servidor ha escrito en un libro, el libro lleva un marcador de función ("Usar signos naturales en los montos de presupuesto") que GnuCash 3.8 introdujo, y GnuCash 3.0–3.7 se niega a abrir un libro marcado con una función que no conoce. GnuCash 3.8 y versiones posteriores marcan cualquier libro con un presupuesto de la misma manera cuando lo abren, así que esto solo importa si aún ejecutas un 3.x más antiguo. El servidor está probado contra GnuCash 5.12.

Apunta el servidor a él

Con el paquete, elige el libro en la configuración de la extensión de GnuCash en Claude Desktop y luego reinicia Claude Desktop. Con una instalación desde clon, establece GNUCASH_BOOK_PATH a la ruta absoluta del libro; consulta Uso de tu propio libro.

O: mantén el libro en PostgreSQL o MySQL

GnuCash también puede mantener un libro en una base de datos en lugar de un archivo, y el servidor también sirve uno de esos. Apúntalo a una cadena de conexión en lugar de una ruta:

{
  "command": "/Users/yourname/.local/bin/gnucash-mcp",
  "args": ["--modules=all"],
  "env": {
    "GNUCASH_BOOK_URI": "postgresql://user:password@localhost:5432/gnucash",
    "GNUCASH_LOG_DIR": "/Users/yourname/gnucash-mcp-logs"
  }
}

Instala el controlador junto al servidor — postgres o mysql (MariaDB usa el mismo). Desde dentro de tu clon (la carpeta gnucash-mcp; consulta instalación desde el código fuente):

uv tool install -e ".[postgres]" --reinstall

Para MySQL / MariaDB la cadena de conexión es mysql+pymysql://user:password@localhost:3306/gnucash y el extra es [mysql]: uv tool install -e ".[mysql]" --reinstall. Las formas más cortas que el propio GnuCash escribe, mysql:// y postgres://, también funcionan; el servidor usa el controlador que el extra instaló.

Instala desde el clon, como arriba, no por nombre: el nombre gnucash-mcp en PyPI pertenece a un proyecto diferente.

Para mover un libro existente: ábrelo en GnuCash, Archivo → Guardar como, elige postgres o mysql y completa los detalles de conexión. (En Debian/Ubuntu esas entradas necesitan sudo apt install libdbd-pgsql or libdbd-mysql, de la misma manera que SQLite3 necesita libdbd-sqlite3; las compilaciones de macOS y Windows incluyen los tres.) Conserva el archivo — sigue siendo una copia de seguridad perfectamente buena de todo hasta el momento en que cambiaste.

Vale la pena saber antes de cambiar:

• GNUCASH_BOOK_PATH y GNUCASH_BOOK_URI son mutuamente excluyentes — un libro es un archivo o una base de datos, y establecer ambos es un error de inicio en lugar de un lanzamiento de moneda sobre en qué libro mayor caen tus escrituras.
• GNUCASH_LOG_DIR se vuelve obligatorio. Los registros de auditoría y depuración normalmente viven en una carpeta junto al archivo del libro; una cadena de conexión no tiene "junto a".
• Un libro por servidor. switch_book coincide con nombres de archivo, por lo que el multi-libro sigue siendo una función de archivo.
• El servidor deja de hacer copias de seguridad. Este es el verdadero intercambio: la red de seguridad automática existe porque puede tomar una instantánea de un archivo, y no puede tomar una instantánea de tu base de datos. create_backup lo dice en lugar de fingir. Configura pg_dump o mysqldump en un horario antes de mover un libro real — consulta docs/RESTORE_FROM_BACKUP.md.
• Tu contraseña se enmascara dondequiera que el servidor nombre el libro — en resultados de herramientas, en el encabezado del panel y en el registro de auditoría — y en cada mensaje de error, línea de registro y error de inicio, incluidos los que escribe un controlador de base de datos. Una contraseña dada como parámetro de consulta (?password=…, sslpassword=…) se enmascara de la misma manera.
• Pon la cadena de conexión en el bloque env, no en la línea de comandos. --book-uri funciona, pero una contraseña en una línea de comandos es visible para cada usuario de la máquina en la lista de procesos. En PostgreSQL también puedes omitir la contraseña de la cadena por completo y dejar que el controlador lea PGPASSWORD o ~/.pgpass.

Ambos dialectos son ejercitados por el conjunto de pruebas y CI: PostgreSQL 16 y MariaDB 11, cada uno contra un servidor real.

---

Elección de un conjunto de módulos

--modules=all es el valor predeterminado fácil — cada herramienta, 86 de ellas. Para el uso diario probablemente querrás menos. Elige el rol que coincida con cómo hablarás con el servidor; también puedes elegir los módulos detrás de cada rol individualmente para un corte más fino.

Rol	Lo que te da	Herramientas
core	Primitivas de libro mayor — cuentas, transacciones, saldos, slots, registro de auditoría, copias de seguridad, balance general, conciliación. Siempre cargado.	29
bookkeeper	Todo excepto negocios: informes, presupuestos, transacciones programadas, precios y lotes de inversión. El conjunto de finanzas personales.	30
investor	Seguimiento de base de costo y gestión de precios solamente (un subconjunto de bookkeeper).	13
business	Clientes, proveedores y empleados; facturas, facturas de proveedores, vales y notas de crédito; impuesto a las ventas, términos de pago, trabajos e informes de proveedores.	27

Elige uno o más, separados por comas:

"args": ["--modules=bookkeeper"]            // personal finance
"args": ["--modules=investor"]              // self-directed investor
"args": ["--modules=business"]              // invoicing, freelance or small business
"args": ["--modules=bookkeeper,business"]   // everything (same as all)

core se añade de todos modos. freelancer y business_complete, los nombres que usaba la 1.4, siguen siendo aceptados y significan business. Los módulos detrás de cada rol (reconciliation, reporting, budgets, scheduling, tax_lots, portfolio, etc.) son seleccionables individualmente también: ejecuta uv run gnucash-mcp --help desde el repositorio para ver el menú completo.

---

Qué puedes pedirle que haga

Un recorrido no exhaustivo. Formula cualquiera de estas frases de forma natural: el asistente las traduce.

Introducir un estado de cuenta completo

"Aquí está mi estado de cuenta de agosto del checking." (adjunta el PDF)

Contrasté 31 líneas con tu libro: 24 nuevas, 6 ya registradas (conciliadas), 1 necesita revisión: aquí está la comparación. Confirma y cerraré el mes: registrado, categorizado y conciliado con el saldo final en un solo paso.

Un estado de cuenta, dos llamadas, un libro cuadradado. La prueba en seco clasifica cada línea con evidencia antes de escribir nada, y la confirmación rechaza todo en bloque en lugar de asentar un mes que no cuadra.

Registrar actividad

"Gasté $47.50 hoy en Safeway en comestibles, pagado con mi Visa."

Registrado: $47.50 de Credit Card:Visa a Expenses:Groceries el 30 abr 2026. Descripción: "Safeway".

Configurar facturas recurrentes

"Configura mi renta como factura recurrente. $1,850 el día 1 de cada mes desde checking."

Transacción programada creada "Monthly Rent": $1,850 mensual, de Assets:Checking a Expenses:Rent. Próximo vencimiento: 1 may 2026.

Seguimiento de inversiones

"Compré $1,000 de VTSAX a $170.99/acción en mi 401(k)."

Compra de VTSAX registrada: 5.85 acciones a $170.99/acción. Base de costo: $1,000.00. Lote creado para el seguimiento de ganancias de capital cuando eventualmente vendas.

Facturación a clientes

"Crea un cliente llamado Acme Corp y factúrales $1,500 por consultoría."

Cliente creado Acme Corp (id 000005) y factura 000019: 1× Consulting a $1,500.00 = $1,500.00. Abierta. Dime cuando estés listo para contabilizarla.

Si abres una factura contabilizada por el servidor en el diálogo Process Payment de GnuCash, configura primero su cuenta "Post To" en la cuenta por cobrar de la factura: el diálogo solo lista los documentos contabilizados en la cuenta seleccionada.

Facturación en moneda extranjera

"Factura a Berlin Digital €4,200 por el retenedor del Q1, vence en 30 días."

Factura EUR 000020 creada para Berlin Digital GmbH: 1× Q1 Retainer a EUR 4,200 = EUR 4,200. Neto 30. Cuando paguen, registraré automáticamente la ganancia/pérdida cambiaria realizada en tu cuenta de FX.

Hacer preguntas

"¿Cuánto gasté con cada proveedor este año?"

Office Depot: $2,340 (4 facturas, $0 pendiente) CloudHost Inc: $1,200 (2 facturas, $600 pendiente) Legal Associates: $3,500 (1 factura, $3,500 pendiente) Total facturado $7,040 / pagado $2,940 / pendiente $4,100.

Conciliación

"Ayúdame a conciliar checking con el estado de abril."

[Te guía paso a paso: extrae los splits no conciliados, te pide confirmar las transacciones compensadas, calcula el saldo corriente, marca los coincidentes como conciliados y deja los descuadres para que los investigues.]

---

Privacidad y seguridad

Tu archivo de libro nunca sale de tu máquina. Este servidor es un proceso local que lee y escribe un archivo local. El asistente de IA con el que hablas (Claude Desktop, etc.) ve los resultados de tus llamadas a herramientas — el mismo contenido que verías en pantalla — pero el archivo en sí permanece donde siempre estuvo.

Cada escritura queda registrada. Un rastro de auditoría legible por humanos vive junto a tu archivo de libro en <your-book>.gnucash.mcp/audit/, un archivo de registro por día. Puedes leerlo en cualquier momento para ver exactamente qué cambió y cuándo. Ejemplo de entrada:

2026-04-30 14:32  POST INVOICE  id:000019
    total: 1500.00  date: 2026-04-30
    account: Assets:Accounts Receivable  txn:a1b2c3d4

Copias de seguridad automáticas. Antes de la primera escritura de cada sesión (y de nuevo cuando una sesión larga cruza a un nuevo período de copia), el servidor hace una instantánea de tu libro en <your-book>.gnucash.mcp/backups/ — así que si algo sale mal, puedes revertir a un estado conocido sin depender de Time Machine ni de tu propio hábito. Las copias se verifican con PRAGMA integrity_check antes de declararse válidas y se omiten cuando el libro no ha cambiado desde la última instantánea. Consulta docs/RESTORE_FROM_BACKUP.md para el procedimiento de reversión.

Marcas de tiempo de lectura: los nombres de archivo de las copias llevan marcas de tiempo UTC (seguras para sistemas de archivos e inequívocas entre viajes y cambios de horario); los registros de auditoría y depuración usan archivos diarios con fecha local, lo que coincide con cómo buscarías "qué pasó el martes". Cerca de la medianoche pueden diferir en un día: tenlo presente al emparejar una copia con el registro de un día.

Los splits conciliados están protegidos. El servidor se niega a eliminar o modificar splits conciliados sin una anulación explícita, así que un prompt descuidado no puede invalidar silenciosamente tu última conciliación bancaria.

Anular ≠ eliminar. Cuando le dices a la IA "anula esta transacción", usa la anulación contable correcta de GnuCash: conserva la transacción para el rastro de auditoría con valores en cero. La eliminación es la opción destructiva; la IA te dirá cuál está haciendo.

Aviso legal: Este software se proporciona "tal cual" bajo la Licencia MIT, sin garantía de ningún tipo. Los autores no son responsables de ninguna pérdida de datos, corrupción o discrepancia financiera derivada de su uso. Eres el único responsable de mantener tus propias copias de seguridad y verificar la exactitud de tus libros.

---

Limitaciones conocidas

• No edites en GnuCash de escritorio y a través del servidor al mismo tiempo. El servidor respeta el bloqueo de GnuCash pero no mantiene uno propio (abre el libro para una llamada a la vez), así que GnuCash no te advertirá que el servidor está usando el libro.
• Libros con "Usar cuentas de trading" activado: las transacciones entre monedas o commodities, incluidas las compras de acciones y fondos, se rechazan porque el servidor aún no puede escribir splits de trading como lo hace GnuCash. Regístralas en GnuCash de escritorio; todo en una sola moneda funciona como siempre.
• GnuCash 3.8 o más reciente. Un libro al que el servidor ha escrito lleva un marcador de funcionalidad que GnuCash 3.0–3.7 no puede abrir.
• Los gastos e ingresos en moneda extranjera se valoran al tipo de cierre de cada mes en los informes de gastos e ingresos, no al efectivo que los pagó; cash_flow informa el efectivo.

La lista completa está en CHANGELOG.md.

---

Limitar lo que la IA puede ver

La descripción de cada herramienta vive en el prompt del sistema de la IA, lo que cuesta contexto en cada mensaje. Reducir el conjunto de herramientas a lo que realmente usas hace cada conversación más barata. Consulta elegir un conjunto de módulos arriba para los cuatro roles (core, bookkeeper, investor, business).

También puedes configurar GNUCASH_MCP_MODULES=core,bookkeeper como variable de entorno en lugar de --modules=... en los argumentos JSON.

---

Novedades en v1.5.0

• Libros en una base de datos. Apunta el servidor a un libro que GnuCash guarda en PostgreSQL o MySQL/MariaDB, no solo un archivo SQLite: consulta O: guarda el libro en PostgreSQL o MySQL. El soporte de PostgreSQL fue contribuido por @vchatela.
• Todo se almacena como lo hace GnuCash de escritorio. Las transacciones programadas se ejecutan en el escritorio con Since Last Run, los presupuestos, las facturas, las notas de crédito, las anulaciones y los precios se leen igual en ambos, y los totales de facturas coinciden con los de GnuCash al céntimo. ¿Actualizas desde 1.4? Lee la guía de actualización primero.
• Pagos anticipados. Registra el sobrepago de un cliente o proveedor como dinero retenido para ellos, liquida una factura posterior con él y descontabiliza una factura pagada sin perder el pago.
• Enlaces Num y de documento en cada herramienta de transacción, con el número usado como verificación de duplicados.
• Un mapa de tu plan de cuentas en el panel, para que el asistente sepa dónde vive cada cuenta antes de preguntar.
• Libros de muestra compilados desde el código fuente, cada uno verificado contra la práctica fiscal de su propio país (EE. UU./Washington, Alemania, China) y actualizados al día en que se compilan.

Las versiones anteriores están en CHANGELOG.md.

---

Solución de problemas

Sin icono de 🔨 martillo, o "herramienta no encontrada"

• Sal de Claude Desktop por completo y vuelve a abrirlo. (Cerrar la ventana no basta: tienes que salir de la aplicación).
• Verifica que las rutas en tu configuración sean absolutas y correctas.
• Revisa el JSON por comas finales: rompen la configuración silenciosamente.

"Libro no encontrado"

• Usa rutas absolutas, no ~ ni rutas relativas.
• Mac/Linux: /Users/yourname/Documents/book.gnucash
• Windows: C:\\Users\\yourname\\Documents\\book.gnucash (barras invertidas duplicadas: requisito de JSON)

"No se puede abrir el libro" / errores de piecash

• Confirma que tu libro esté en formato SQLite, no XML.
• Asegúrate de que GnuCash no esté abierto con el mismo libro: bloqueo de archivo. El servidor respeta el bloqueo de GnuCash pero deliberadamente no toma ninguno propio (mantiene el libro para una llamada a la vez), así que GnuCash abrirá un libro que el servidor está usando sin advertencia. No edites en ambos a la vez.
• Intenta abrir el libro en GnuCash mismo para verificar que no esté corrupto.

Docker: "tanto GNUCASH_BOOK_PATH como GNUCASH_BOOK_URI están configurados"

La imagen incluye GNUCASH_BOOK_PATH apuntando a sus libros de demostración incluidos. Para servir un libro de base de datos desde ella, limpia ese valor predeterminado en la línea de comandos (-e GNUCASH_BOOK_PATH=) junto a tu GNUCASH_BOOK_URI; para servir un archivo montado, configura GNUCASH_BOOK_PATH a la ruta montada y ejecuta el contenedor como el usuario que posee el archivo (--user "$(id -u):$(id -g)").

"Cuenta no encontrada"

• Usa rutas de cuenta completas: Expenses:Groceries, no solo Groceries.
• O pide al asistente que liste las cuentas: "Lista mis cuentas."

Múltiples procesos del servidor tras reiniciar el cliente

Claude Desktop (y algunos otros clientes MCP) puede generar brevemente dos o tres copias del servidor al relanzarse. Esto es comportamiento del cliente, no un error del servidor, y es en su mayoría inofensivo: el servidor abre tu libro por solicitud y libera el bloqueo de archivo entre llamadas, así que los procesos superpuestos compiten solo por momentos. Si ves errores persistentes de Lock on the file después de reiniciar el cliente, sal del cliente por completo, confirma con pgrep -fl gnucash-mcp que no queden procesos sueltos y relanza.

Algo salió mal

• Abre el registro de auditoría en <your-book>.gnucash.mcp/audit/: cada escritura desde que el servidor se ejecutó por primera vez está ahí con detalle de antes/después.
• Si necesitas revertir, docs/RESTORE_FROM_BACKUP.md te guía paso a paso.

---

Apoya el proyecto

Si gnucash-mcp te resulta útil, considera invitarme un café. Ayuda a mantener el desarrollo en marcha.

---

Para desarrolladores

La guía para contribuidores y las notas de diseño viven en CLAUDE.md. Orientación rápida:

uv sync --extra dev
uv run pytest                       # 3,300+ tests as of v1.5.0, parallel by default
uv run ruff check src/ tests/
uv run black --check src/ tests/

El comando gnucash-mcp instalado sigue tu clon en vivo: sirve la rama en la que esté el checkout, así que cambiar de rama cambia el código servido en el próximo reinicio: útil para probar, vale la pena recordarlo cuando olvidas que estás a mitad de rama. Para ejecutar un checkout DIFERENTE (un segundo worktree) sin tocar la instalación, uv run --directory PATH gnucash-mcp sigue ejecutando cualquier directorio al que lo apuntes.

El servidor está construido sobre piecash (interfaz Python para libros SQLite de GnuCash) y el MCP Python SDK. Aproximadamente 18,000 líneas de código fuente Python, 20,000 líneas de pruebas, modularizado para que los módulos deshabilitados no cuesten nada en tiempo de ejecución.

Licencia

MIT.

Agradecimientos

• GnuCash: el software de contabilidad gratuito y de código abierto que este servidor hace conversacional.
• piecash: interfaz Python para libros SQLite de GnuCash.
• MCP Python SDK: la implementación del Model Context Protocol.