QuickBooks Online MCP Server

Servidor MCP de QuickBooks Online para facturas, clientes y pagos. OAuth 2.1 + PKCE, stdio/HTTP.

GitHubPrueba este MCPPatrocinado

Documentación

Servidor MCP de QuickBooks Online

CI Python 3.11+ License: MIT

Servidor MCP de QuickBooks Online para Claude Desktop y cualquier cliente MCP, escrito en Python sobre el SDK oficial de MCP (FastMCP). Expone 18 herramientas sobre facturas, clientes y pagos (crear, leer, actualizar, eliminar, listar, buscar), además de recursos de solo lectura sobre la empresa y las cuentas por cobrar, detrás de un flujo real de OAuth 2.1 con código de autorización + PKCE, renovación automática de tokens, limitación de velocidad del lado del cliente que respeta los límites de QuickBooks, y errores estructurados que le indican al agente qué hacer a continuación. Funciona sobre stdio y HTTP Streamable.

Relacionados: Servidor MCP de HubSpot CRM · Puerta de enlace de auditoría MCP · Lo que realmente requiere el MCP de producción

Arquitectura

flowchart LR
    Agent["MCP client<br/>(Claude Desktop / HTTP)"]
    subgraph Server["mcp-quickbooks (FastMCP)"]
        Tools["18 tools<br/>invoices · customers · payments"]
        Resources["resources<br/>company · receivables · customers"]
        Client["QBOClient<br/>retry · backoff · error mapping"]
        RL["RateLimiter<br/>per-second + per-minute buckets"]
        Auth["AuthManager<br/>OAuth 2.1 + PKCE · token refresh"]
        Store[("token store<br/>.qbo_tokens.json")]
    end
    QBO["Intuit QuickBooks Online API<br/>/v3/company/{realmId}"]

    Agent <-->|stdio / streamable-http| Tools
    Agent <-->|resources/read| Resources
    Tools --> Client
    Resources --> Client
    Client --> RL
    Client --> Auth
    Auth <--> Store
    Auth <-->|token + refresh| QBO
    Client -->|REST + query| QBO

El servidor no mantiene estado ni almacena datos de clientes: es un proxy sin estado sobre la API REST de QuickBooks. Los tokens residen en un archivo local que tú controlas; el cliente se implementa con sus propias credenciales de Intuit.

Herramientas

Cada herramienta devuelve un resultado estructurado { "ok": true, ... }, o { "ok": false, "error": {...} } con un suggestion. Cada una incluye anotaciones MCP (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) y un esquema de salida declarado.

  • create_customer: Crear un cliente. El nombre para mostrar debe ser único; QuickBooks rechaza duplicados con el error 6240.
  • get_customer: Leer un cliente por Id, incluidos saldo, datos de contacto y el SyncToken actual.
  • update_customer: Actualización parcial de un cliente existente. Requiere el Id y un SyncToken reciente.
  • delete_customer: Desactivar un cliente (QuickBooks no permite eliminación definitiva de clientes), preservando el historial.
  • list_customers: Listar clientes, primero los más recientemente actualizados, con paginación controlada por el llamador.
  • search_customers: Buscar clientes por prefijo del nombre para mostrar, correo electrónico exacto o indicador de activo.
  • create_invoice: Crear una factura para un cliente existente con uno o más conceptos.
  • get_invoice: Leer una factura por Id, incluidas líneas, totales, saldo y el SyncToken actual.
  • update_invoice: Reemplazar una factura. Las líneas se reemplazan por completo, así que envía todas las líneas con las que debe quedar.
  • delete_invoice: Eliminar una factura de forma permanente. Requiere el Id y un SyncToken reciente.
  • list_invoices: Listar facturas, primero la fecha de transacción más reciente, con paginación controlada por el llamador.
  • search_invoices: Buscar facturas por Id de cliente, rango de fechas de transacción o número de documento.
  • create_payment: Registrar un pago recibido, opcionalmente aplicado a una factura específica.
  • get_payment: Leer un pago por Id, incluidas transacciones vinculadas y el SyncToken actual.
  • update_payment: Reemplazar un pago. Quitar el vínculo de la factura reabre el saldo de esa factura.
  • delete_payment: Eliminar un pago de forma permanente. Cualquier factura que haya saldado vuelve a estar impaga.
  • list_payments: Listar pagos, primero la fecha de transacción más reciente, con paginación controlada por el llamador.
  • search_payments: Buscar pagos por Id de cliente o rango de fechas de transacción.

Recursos

JSON de solo lectura:

  • qbo://company: perfil de la empresa y dirección legal
  • qbo://summary/receivables: conteos de facturas abiertas/vencidas y saldo pendiente
  • qbo://summary/customers: clientes activos ordenados por saldo pendiente

Ámbitos de privilegio mínimo

El ámbito predeterminado es solo com.intuit.quickbooks.accounting. Agrega com.intuit.quickbooks.payment (mediante QBO_SCOPES) únicamente si conectas el procesamiento de pagos. La cadena de ámbito se valida al inicio contra el conjunto de ámbitos conocido de Intuit, de modo que un error tipográfico falla rápido en lugar de autorizar de menos en silencio. Los ámbitos de identidad (openid, profile, email) nunca se solicitan a menos que optes por ellos.

Limitación de velocidad y reintentos

Un limitador de doble cubo de tokens limita el tráfico saliente bajo los techos por segundo y por minuto de QuickBooks (configurable mediante QBO_REQUESTS_PER_SECOND / QBO_REQUESTS_PER_MINUTE). En 429, el cliente respeta el encabezado Retry-After; en 429/5xx sin uno, usa retroceso exponencial con fluctuación, hasta QBO_MAX_RETRIES. Un único 401 activa una renovación de token y un reintento transparente.

Inicio rápido

uv venv --python 3.12 .venv
uv pip install -e ".[dev]"

cp .env.example .env       # fill in QBO_CLIENT_ID / QBO_CLIENT_SECRET
mcp-quickbooks auth        # opens Intuit, captures the redirect, stores tokens
mcp-quickbooks status      # verify the token refreshes

mcp-quickbooks stdio       # run over stdio (Claude Desktop)
mcp-quickbooks http --port 8000   # run over Streamable HTTP

Las credenciales se leen de forma diferida. El servidor arranca, responde a initialize y sirve tools/list sin ninguna variable QBO_* configurada; una llamada a herramienta sin credenciales devuelve un 401 estructurado que le indica al llamador qué configurar. Eso mantiene la introspección del registro y las pruebas de humo del contenedor funcionando sin secretos.

Claude Desktop

{
  "mcpServers": {
    "quickbooks": {
      "command": "mcp-quickbooks",
      "args": ["stdio"],
      "env": { "QBO_ENVIRONMENT": "sandbox" }
    }
  }
}

Docker

docker build -t mcp-quickbooks .
docker run --rm -i --env-file .env mcp-quickbooks

Ejecución contra un sandbox real de Intuit

  1. Crea una aplicación en el portal para desarrolladores de Intuit y abre su sección Keys & OAuth. Copia el id y el secreto de cliente de Development.
  2. Agrega una URI de redirección que coincida con QBO_REDIRECT_URI en tu .env (predeterminado http://localhost:8765/callback).
  3. Crea una empresa sandbox desde el panel del desarrollador; su id de empresa es tu QBO_REALM_ID.
  4. Configura QBO_ENVIRONMENT=sandbox, completa QBO_CLIENT_ID / QBO_CLIENT_SECRET y luego ejecuta mcp-quickbooks auth. El flujo del navegador devuelve un realmId automáticamente; se almacena junto con los tokens.
  5. mcp-quickbooks status confirma que los tokens se renuevan. Ahora estás operando el sandbox en vivo.

Cambia QBO_ENVIRONMENT=production (con claves de producción y una empresa conectada) para apuntar a libros reales. Las credenciales y los tokens son tuyos; nada se confirma: .env y .qbo_tokens.json están en gitignore.

Pruebas

La suite se ejecuta completamente sin conexión. Cada llamada a QuickBooks y OAuth la atiende un simulacro en memoria (tests/fake_qbo.py) sembrado con fixtures de estilo grabado en tests/fixtures/, conectado mediante un transporte simulado httpx: sin red, sin credenciales reales.

uv run pytest

Metadatos del registro

server.json describe el servidor para el registro MCP, y .mcp.json es el fragmento de configuración de cliente que buscan los rastreadores de directorios. La publicación se deja intencionalmente como un paso manual. Consulta PUBLISHING.md. Nada aquí se envía a ningún registro.

Contrátame

Hago que las integraciones de la era de la IA y críticas para el dinero sean seguras para producción: autenticación real, límites de velocidad reales, manejo de errores real, pruebas reales. Disponible para construcciones de servidores MCP y endurecimiento de integraciones de API. Portafolio y contacto: https://amin-ale.github.io/portfolio-site · amin.ale.business@gmail.com

Licencia

MIT: consulta LICENCIA.