quickbooks-mcp-server

Un servidor MCP de un solo archivo que le da a Claude acceso completo de lectura y escritura a QuickBooks Online, además de herramientas de conciliación que encuentran lo que un humano que revisa un registro no logra ver.

$ qbo_health_check

  transport ...... stdio (Claude Desktop, Claude Code, claude.ai)
  api ............ QuickBooks Online v3
  tools .......... 22
  version ........ 2.0.0
  deploy ......... local, or HTTP on a Raspberry Pi behind Tailscale

Por qué existe esto

Las consultas contables casi nunca son una sola pregunta. "¿Le pagamos dos veces a ese proveedor?" implica listar las compras, agrupar por importe y proximidad de fecha, cruzar con el feed del banco y luego comprobar si el duplicado se anuló después. Eso es un bucle, y los bucles son trabajo de un agente.

La apuesta de diseño: dar al modelo un conjunto pequeño de herramientas componibles y dejar que haga el razonamiento, en lugar de incluir un único reconcile() que codifique mi criterio sobre lo que significa una discrepancia.

Esa apuesta es la razón por la que la v2.0.0 tiene 22 herramientas, frente a las 45 de la v1.0.0. La primera versión tenía una herramienta para cada pregunta que me había hecho. Al final, la mayoría eran solo el modelo combinando dos primitivas — así que las primitivas se quedaron y las compuestas se eliminaron. Consulta CHANGELOG.md para el mapa de migración.

Related MCP server: penni-mcp

Herramientas

$ qbo --list-tools

  read
    qbo_company_info            qbo_get_preferences         qbo_health_check
    qbo_list_accounts           qbo_list_customers          qbo_get_customer
    qbo_list_bills              qbo_list_deposits           qbo_get_entity
    qbo_get_invoice             qbo_get_transaction         qbo_get_transfer
    qbo_get_journal_entry       qbo_get_report              qbo_account_register

  write
    qbo_create_invoice          qbo_create_payment          qbo_create_purchase
    qbo_delete_journal_entry    qbo_delete_purchase         qbo_delete_transfer
    qbo_batch_delete

  reconciliation
    qbo_detect_bank_feed_gaps       find dates where the feed silently stopped
    qbo_find_duplicate_transactions near-match scan across amount + date window
    qbo_duplicate_scan_by_account   the same, scoped to one account
    qbo_analyze_reconciliation      month-end variance with the arithmetic shown

Las herramientas de conciliación son las que merece la pena copiar. Las lagunas del feed bancario son el fallo que nadie detecta — el feed se detiene durante cuatro días, las transacciones nunca llegan y los libros cuadran perfectamente contra una imagen incompleta. No se produce ningún error. Aparece en marzo, cuando el cierre del año no cuadra.

Instalación

$ git clone https://github.com/rjpaganini/quickbooks-mcp-server
$ cd quickbooks-mcp-server
$ pip install -r requirements.txt
$ cp .env.example .env        # then fill in your QBO app credentials

Registra una aplicación en developer.intuit.com para obtener un ID de cliente y un secreto. Necesitarás:

  QB_REALM_ID          your company id
  QB_CLIENT_ID         from the Intuit developer app
  QB_CLIENT_SECRET     from the Intuit developer app
  QB_REFRESH_TOKEN     from the OAuth playground
  QB_ACCESS_TOKEN      refreshed automatically once seeded
  QB_SANDBOX           true while testing — set false deliberately

Después, apunta tu cliente MCP al servidor:

{
  "mcpServers": {
    "quickbooks": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

Seguridad

Este servidor puede eliminar datos en una contabilidad real. No es una hipótesis — qbo_batch_delete existe porque limpiar manualmente una importación incorrecta es una agonía.

Lee SECURITY.md antes de conectarlo a un archivo de una empresa real. La versión corta: empieza en un sandbox, mantén QB_SANDBOX=true hasta que lo hayas visto funcionar y trata las herramientas de escritura y eliminación como tratarías rm con un comodín.

$ pytest                       # unit tests, no network
$ pytest -m live               # smoke tests against a live sandbox company

Notas

• Un único archivo a propósito. server.py es grande, pero todo se puede buscar con grep y no hay un grafo de imports que tener que meter en la cabeza.

• También se ejecuta como servicio HTTP en una Raspberry Pi mediante deploy-to-pi.sh, que es la forma en la que lo alcanzo desde claude.ai en el móvil usando Tailscale.

• En este repositorio no hay credenciales, datos de empresa ni registros financieros.

Licencia

MIT.