qbo-mcp

El servidor del Protocolo de Contexto de Modelo (MCP) para QuickBooks Online. Conecta Claude a tu contabilidad —clientes, proveedores, facturas, recibos y el plan de cuentas— en modo de solo lectura, en cinco minutos.

👁 License: MIT
👁 Python 3.10+
👁 MCP

Por qué existe esto

Aproximadamente siete millones de empresas llevan su contabilidad en QuickBooks Online. Intuit publica una API REST capaz, pero no un servidor MCP oficial, por lo que cada equipo que quiere que Claude (o cualquier asistente de IA compatible con MCP) vea sus libros termina escribiendo desde cero el mismo código de pegamento para OAuth y paginación.

Si utilizas Claude para gestionar las finanzas del día a día —perseguir cuentas por cobrar, verificar cuentas por pagar, preparar actualizaciones para la junta directiva—, esa brecha es la diferencia entre que "¿cuánto nos debía Acme a finales de marzo?" funcione de inmediato y que "¿cuánto nos debía Acme a finales de marzo?" requiera una integración personalizada.

qbo-mcp cierra esa brecha. Es un servidor MCP pequeño, bien probado y con licencia MIT que expone ocho endpoints de solo lectura de QBO a cualquier cliente MCP. Construido a partir de años de ejecutar automatización de QBO en producción contra flujos de dinero reales; cada caso extremo que surgió en producción (rotación de tokens, retroceso 429, caducidad a mitad de página, escape de cadenas de consulta) se maneja en client.py para que no tengas que aprenderlo por las malas.

Related MCP server: QuickBooks MCP Server

Qué puedes hacer con esto

Conecta este servidor a Claude Code, Claude Desktop o cualquier host MCP, y luego pregunta cosas como:

• "Busca todos los clientes que coincidan con 'Acme' y muéstrame sus saldos."

• "¿Cuánto le debemos a WidgetCo ahora mismo? Enumera las facturas pendientes."

• "Extrae todas las facturas impagadas creadas este mes y agrúpalas por cliente."

• "¿Cómo es nuestro plan de cuentas? Enumera todas las cuentas bancarias y de otros activos corrientes con su saldo actual."

• "Compara el volumen de facturas de la semana pasada con la misma semana del mes anterior."

Claude lee tus libros directamente. Sin copiar y pegar, sin hojas de cálculo, sin tuberías personalizadas.

Herramientas (v0.1, todas de solo lectura)

Los endpoints de escritura (crear factura, crear recibo, publicar asiento de diario) están intencionalmente no incluidos en la v0.1. Están planificados para la v0.2 una vez que la ergonomía de solo lectura se estabilice. No lanzaremos una herramienta de escritura que acceda a tus libros hasta que la superficie de lectura haya sido probada durante un ciclo de lanzamiento.

Instalación

pip install qbo-mcp

La v0.1 se envía desde este repositorio. La publicación en PyPI está pendiente; por ahora, instala con pip install git+https://github.com/alveyautomation/qbo-mcp o clona y ejecuta pip install -e . localmente.

Configuración única de OAuth

QBO utiliza OAuth 2.0 con tokens de actualización rotativos. Solo haces este proceso una vez, luego qbo-mcp se mantiene autenticado para siempre (siempre que se ejecute al menos una vez cada 100 días). Tiempo total: unos 60 segundos.

1. Crea una aplicación en https://developer.intuit.com/. Elige el ámbito Accounting. Copia el client_id y el client_secret.

2. Visita el OAuth Playground en https://developer.intuit.com/app/developer/playground. Selecciona tu aplicación, elige el entorno (Sandbox o Producción) y haz clic en Get Authorization Code. Inicia sesión en la empresa de QuickBooks que deseas exponer.

3. Intercambia el código por tokens: el Playground lo hace por ti. Copia:

   • refresh_token (cadena larga, dura 100 días de inactividad)

   • realmId (numérico, identifica tu empresa de QBO)

4. Guárdalos en .env:

QBO_CLIENT_ID=ABxxxxxxxxxxxxxx
QBO_CLIENT_SECRET=xxxxxxxxxxxxxxxx
QBO_REFRESH_TOKEN=ABxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
QBO_REALM_ID=1234567890123456
QBO_ENVIRONMENT=production # or "sandbox"

Eso es todo. La primera llamada a la herramienta intercambia el token de actualización por un token de acceso; las llamadas posteriores reutilizan el token de acceso en caché hasta que caduca (~55 minutos), momento en el cual el cliente se actualiza silenciosamente.

Rotación de tokens de actualización: Intuit emite un nuevo token de actualización en cada actualización e invalida inmediatamente el anterior. Si tu despliegue se ejecuta en un único proceso de larga duración, esto es invisible. Si tu despliegue se reinicia a menudo (contenedores, serverless), persiste el token rotado. Suscríbete a QBOClient(on_refresh_token_rotated=...) para capturar cada rotación. Consulta SECURITY.md para conocer la historia completa.

Conectar a Claude Code

Añade a ~/.claude/claude_code_config.json (o a la configuración MCP de tu proyecto):

{
 "mcpServers": {
 "qbo": {
 "command": "qbo-mcp",
 "env": {
 "QBO_CLIENT_ID": "ABxxxxxxxxxxxxxx",
 "QBO_CLIENT_SECRET": "xxxxxxxxxxxxxxxx",
 "QBO_REFRESH_TOKEN": "ABxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
 "QBO_REALM_ID": "1234567890123456",
 "QBO_ENVIRONMENT": "production"
 }
 }
 }
}

Reinicia Claude Code. Las ocho herramientas qbo_* aparecerán en cualquier sesión nueva.

Conectar a Claude Desktop

Edita ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows) y añade el mismo bloque mcpServers que arriba. Reinicia la aplicación de escritorio.

Referencia de herramientas

Cada herramienta devuelve un sobre JSON:

{ "ok": true, "data": { ... } }
{ "ok": false, "error": "human-readable message" }

qbo_search_customers

qbo_search_customers(query: str, limit: int = 50)

Coincidencia de subcadena con Customer.DisplayName. La consulta se escapa antes de incrustarse en el lenguaje de consulta de QBO, por lo que los apóstrofes (O'Brien) y los guiones bajos (acme_test) son seguros.

Ejemplo de respuesta:

{
 "ok": true,
 "data": {
 "customers": [
 { "Id": "1001", "DisplayName": "Acme Corp", "Balance": 1250.00 }
 ],
 "count": 1,
 "query": "acme",
 "limit": 50
 }
}

qbo_get_customer

qbo_get_customer(customer_id: str)

Obtiene el registro completo del cliente por Id. Devuelve data: null cuando el Id no existe (404).

qbo_search_vendors / qbo_get_vendor

Simétrico al par de clientes, pero contra la entidad Vendor.

qbo_search_invoices

qbo_search_invoices(
 date_from: str, # ISO date "YYYY-MM-DD"
 date_to: str, # ISO date "YYYY-MM-DD"
 status: str | None = None, # "open" | "paid" | None
 limit: int = 200, # max 2000
)

La ventana es inclusiva en Invoice.TxnDate. El filtro status es una conveniencia sobre el campo Balance de QBO: "open" devuelve facturas con Balance > 0, "paid" devuelve facturas con Balance = 0.

La paginación se maneja de forma transparente: el endpoint de consulta de QBO requiere cláusulas explícitas STARTPOSITION / MAXRESULTS, y el cliente recorre las páginas hasta que se alcanza el limit o el upstream devuelve una página corta. La respuesta incluye limit_reached: true cuando limit fue la condición de parada.

qbo_get_invoice

qbo_get_invoice(invoice_id: str)

Devuelve el registro completo de la factura (con Line[]), o data: null para un 404.

qbo_search_bills / paridad de qbo_get_invoice

qbo_search_bills refleja qbo_search_invoices pero contra la entidad Bill (lado del proveedor). Mismas semánticas de fecha, mismo filtro de estado.

qbo_get_chart_of_accounts

qbo_get_chart_of_accounts()

Devuelve cada cuenta activa en el reino. Cada registro incluye Id, Name, AccountType, AccountSubType, Classification y CurrentBalance, entre otros campos de QBO. Útil para fundamentar cualquier pregunta de "¿dónde se registró esta transacción?".

Desarrollo local

git clone https://github.com/alveyautomation/qbo-mcp
cd qbo-mcp
python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest # 50+ tests, ~3s

Hooks de pre-commit (gitleaks, trufflehog, ruff, formateador, depurador de huellas de inquilino):

pip install pre-commit
pre-commit install

Las pruebas de integración contra un reino sandbox real de QBO están protegidas detrás de QBO_INTEGRATION_TESTS=1. No son necesarias para la contribución normal.

Solución de problemas

Failed to refresh QBO access token — el token de actualización ha sido rotado sin que te dieras cuenta, o el client_id / client_secret de la aplicación es incorrecto. Los tokens de actualización se invalidan tan pronto como se emite uno nuevo, por lo que si dos procesos comparten un token de actualización, el que se actualice primero gana. Solución: persiste los tokens rotados (consulta on_refresh_token_rotated) o ejecuta solo un servidor por credencial de token de actualización.

Missing required environment variables — el servidor intentó iniciarse antes de que se cargara su .env. Exporta las variables en el shell principal o asegúrate de que la configuración de tu host MCP las incluya en el bloque env.

Resultados vacíos a pesar de datos conocidos — confirma que QBO_ENVIRONMENT coincide con la credencial. Un token de actualización de sandbox contra el host de API de producción (o viceversa) se autenticará pero devolverá una empresa vacía.

Ventanas de fechas grandes lentas — el endpoint de consulta de QBO pagina con un límite estricto de 1000 filas por página. El cliente recorre las páginas de forma transparente, pero un escaneo de facturas de 5 años sigue significando muchos viajes de ida y vuelta. Considera ajustar date_from / date_to o filtrar por status.

Transient QBO error: HTTP 429 — el limitador de velocidad de Intuit se activó. El cliente reintenta automáticamente con retroceso exponencial; si ves esto en la salida de la herramienta, has superado el QBO_MAX_RETRIES configurado. Auméntalo o ralentiza tus consultas.

Contribución

Las propuestas y solicitudes de extracción son bienvenidas. Por favor:

• Ejecuta pytest antes de abrir una PR (pip install -e ".[dev]").

• Ejecuta pre-commit run --all-files.

• Mantén las adiciones al alcance de solo lectura de la v0.1. Los endpoints de escritura llegarán en la v0.2.

• Datos sintéticos solo en pruebas: sin nombres de clientes reales, nombres de proveedores o IDs de reino.

Licencia

MIT: consulta LICENSE.

Descargo de responsabilidad

qbo-mcp es una integración de terceros no oficial. No está respaldada, afiliada ni apoyada por Intuit Inc. "QuickBooks" y "QuickBooks Online" son marcas comerciales de Intuit Inc. Úsalo bajo tu propio riesgo; verifica el comportamiento contra tu reino antes de depender de él para decisiones de producción.

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers

Tools

• qbo_get_chart_of_accountsA
• qbo_get_customerA
• qbo_get_invoiceA
• qbo_get_vendorA
• qbo_search_billsA
• qbo_search_customersA
• qbo_search_invoicesA
• qbo_search_vendorsA