QontoCtl

CLI y servidor MCP para la API bancaria de Qonto.

Este proyecto es una contribución de Alexey Pelykh.

Proyecto no oficial. QontoCtl es independiente y no está afiliado, respaldado ni soportado por Qonto. Consulta el Aviso legal.

Qué Hace

QontoCtl permite a los asistentes de IA (Claude, etc.) interactuar con Qonto a través del Model Context Protocol. Puede:

• Organizaciones — recupera los detalles y ajustes de la organización
• Cuentas — lista, crea, actualiza y cierra cuentas bancarias; descarga certificados IBAN
• Transacciones — lista, busca y filtra transacciones bancarias; gestiona los adjuntos de las transacciones
• Extractos bancarios — lista, consulta y descarga extractos bancarios
• Etiquetas — gestiona etiquetas y categorías de transacciones
• Membresías — consulta los miembros del equipo, muestra la membresía actual, invita nuevos miembros
• Beneficiarios SEPA — lista, añade, actualiza, confía/no confía en beneficiarios SEPA
• Transferencias SEPA — lista, crea y cancela transferencias; descarga justificantes; verifica beneficiarios
• Transferencias internas — crea transferencias entre cuentas de la misma organización
• Transferencias masivas — lista, consulta y crea lotes de transferencias SEPA masivas
• Transferencias recurrentes — lista, consulta, crea y cancela transferencias recurrentes
• Transferencias internacionales (SWIFT) — crea transferencias SWIFT y gestiona beneficiarios internacionales
• Tarjetas — lista, crea, actualiza, bloquea/desbloquea, reporta pérdida/robo y descarta tarjetas
• Equipos — lista y crea equipos
• Webhooks — crea y gestiona suscripciones de webhook
• Enlaces de pago — crea, desactiva y gestiona enlaces de pago respaldados por Stripe
• Seguros — muestra, crea y actualiza contratos de seguro y gestiona documentos
• Terminales (TPV) — lista los terminales de Qonto e inicia pagos en terminal
• Productos — lista los productos del catálogo
• Clientes — lista, crea, actualiza y elimina clientes
• Facturas de clientes — ciclo de vida completo: crear, actualizar, finalizar, enviar, marcar como pagada, cancelar, subir archivos
• Presupuestos — crea, actualiza, elimina y envía presupuestos
• Notas de crédito — lista y consulta notas de crédito
• Facturas de proveedores — lista, consulta y crea facturas de proveedores en masa
• Solicitudes — lista las solicitudes de la organización
• Adjuntos — sube y consulta adjuntos
• Facturación electrónica — recupera los ajustes de facturación electrónica

QontoCtl y el MCP oficial de Qonto

QontoCtl es un proyecto independiente y no oficial — no afiliado ni respaldado por Qonto.

Qonto ofrece su propio servidor MCP oficial — alojado, gratuito en todos los planes e instalable con un clic desde Claude, ChatGPT, Cursor y más. Si quieres hablar con tus finanzas — «muestra mis saldos», «grafica el gasto del último mes», «redacta una factura» — es una opción excelente y bien elaborada.

QontoCtl está diseñado para un trabajo diferente: automatizar Qonto, no solo conversar con él.

El MCP oficial es un asistente alojado al que accedes como usuario. QontoCtl es un kit de herramientas local y de código abierto — una CLI, un servidor MCP y una librería — que se ejecuta en tu propia máquina con tus propias credenciales, incluso como cuenta de servicio sin interfaz.

_{Comparación basada en la documentación pública del MCP de Qonto a julio de 2026.}

_{* Las transferencias a beneficiarios no verificados aún requieren tu aprobación de Autenticación Reforzada del Cliente, como debe ser. QontoCtl gestiona la continuación de SCA para que los flujos automatizados — hacia beneficiarios de confianza y entre tus propias cuentas — se completen sin una persona en el terminal.}

QontoCtl también admite múltiples organizaciones de Qonto desde una sola configuración mediante perfiles con nombre — útil para contables, sociedades holding y cualquiera que lleve la contabilidad de varias entidades.

El MCP oficial habla con Qonto. QontoCtl lo automatiza. Muchas personas usarán ambos — el MCP oficial en una ventana de chat, QontoCtl en un pipeline.

Requisitos previos

• Node.js >= 24
• Una cuenta empresarial de Qonto con acceso a la API

Instalación

npm install -g qontoctl

O ejecútalo directamente con npx:

npx qontoctl --help

O instálalo mediante Homebrew:

brew install qontoctl/tap/qontoctl

Inicio rápido

# 1. Install
npm install -g qontoctl

# 2. Create a profile with your Qonto API credentials
qontoctl profile add mycompany

# 3. Test the connection
qontoctl profile test --profile mycompany

# 4. List your accounts
qontoctl account list --profile mycompany

Integración con MCP

QontoCtl implementa el Model Context Protocol (MCP), lo que permite a los asistentes de IA interactuar con tu cuenta de Qonto mediante lenguaje natural.

Configuración del cliente MCP

{
    "mcpServers": {
        "qontoctl": {
            "command": "npx",
            "args": ["qontoctl", "mcp"]
        }
    }
}

claude mcp add qontoctl -- npx qontoctl mcp

{
    "mcpServers": {
        "qontoctl": {
            "command": "npx",
            "args": ["qontoctl", "mcp"]
        }
    }
}

{
    "mcpServers": {
        "qontoctl": {
            "command": "npx",
            "args": ["qontoctl", "mcp"]
        }
    }
}

Apuntar MCP a un archivo de configuración no predeterminado

El servidor MCP no tiene opciones de CLI. Para cargar credenciales desde un archivo de configuración distinto de ~/.qontoctl.yaml, establece QONTOCTL_CONFIG_FILE en el bloque env del host:

{
    "mcpServers": {
        "qontoctl": {
            "command": "npx",
            "args": ["qontoctl", "mcp"],
            "env": {
                "QONTOCTL_CONFIG_FILE": "/abs/path/to/qontoctl.yaml",
            },
        },
    },
}

La ruta se captura al iniciar el servidor. Consulta docs/configuration.md para conocer la cadena completa de resolución.

Herramientas MCP disponibles

Ejemplos de solicitudes

Una vez configurado, puedes preguntar a tu asistente de IA cosas como:

• "Mostrar mis saldos de cuenta de Qonto"
• "Listar transacciones recientes superiores a 1000 EUR"
• "¿Cuáles fueron los pagos con tarjeta del mes pasado?"
• "Mostrar todos los miembros del equipo en mi organización"
• "Listar extractos bancarios de enero de 2026"
• "Crear un resumen de los débitos de esta semana"

Continuación de SCA

Algunas operaciones de escritura de Qonto — crear una transferencia, modificar una tarjeta, aprobar una solicitud — requieren Autenticación Reforzada del Cliente (SCA): el usuario debe aprobar la solicitud en la aplicación móvil de Qonto antes de que se ejecute. QontoCtl envuelve cada herramienta de escritura MCP protegida por SCA con un flujo de continuación para que el cliente LLM nunca tenga que reimplementar el sondeo.

Cómo se comporta una herramienta de escritura envuelta

Cuando una herramienta protegida por SCA (p. ej. transfer_create, card_create, beneficiary_trust, request_approve) recibe un desafío SCA 428, el envoltorio sondea la sesión SCA en línea. Si el usuario aprueba dentro de la ventana de sondeo, la herramienta devuelve el resultado de éxito de la operación de forma transparente — el LLM nunca ve el intercambio SCA. Si el sondeo agota el tiempo (o el sondeo está deshabilitado), la herramienta devuelve una respuesta pendiente de SCA estructurada que incluye el token de sesión e instrucciones para continuar.

Cada herramienta envuelta expone dos campos de entrada opcionales para este flujo:

• wait — segundos máximos para sondear en línea antes de recurrir a la respuesta pendiente.
• sca_session_token — vincular un desafío SCA previamente aprobado a un reintento.

El wait control

El límite superior de 120 es el tope máximo impuesto mediante Zod en el límite de entrada. El límite práctico es el tiempo de espera de solicitud de tu host MCP: Claude Desktop fija aproximadamente 60 s y el límite efectivo de Cursor es de aproximadamente 30 s, por lo que los valores superiores a esos aparecerán como tiempos de espera del host antes de que el wrapper resuelva. Usa un wait pequeño (p. ej., 5-10) cuando el LLM espera que el usuario esté presente y dispuesto a aprobar de inmediato. Usa wait: false (o wait: 0) para flujos puros de dos pasos donde el LLM y el usuario conversan fuera de banda entre el desafío SCA y el reintento.

Recurso de dos pasos (continuación fuera de banda)

Cuando la consulta no se resuelve, la respuesta pendiente de SCA incluye:

• Un mensaje dirigido al usuario: "SCA required. The user must approve this operation on their Qonto mobile app."
• Una línea de Session token: <token> (validez del token: 15 minutos desde su emisión).
• Instrucciones paso a paso para continuar.

El LLM (o el usuario) puede entonces:

1. Consultar el estado de la sesión con la herramienta sca_session_show, pasando el token capturado. Devuelve waiting, allow o deny.
2. Reintentar la herramienta original una vez que el estado sea allow, pasando los mismos parámetros más sca_session_token: "<token>". El wrapper invoca la operación exactamente una vez con el token vinculado: no se realiza una segunda consulta.

Vinculación dinámica PSD2. El token de sesión SCA está vinculado a los parámetros de la solicitud original (importe, beneficiario). Reutilizar un token contra una operación diferente es rechazado por Qonto. Vuelve a emitir un desafío SCA llamando nuevamente a la herramienta original siempre que los parámetros necesiten cambiar.

Reintento proporcionado por el llamador (sca_session_token)

Cuando sca_session_token está configurado en una herramienta de escritura envuelta, el wrapper:

• Invoca la operación exactamente una vez.
• Omite la consulta por completo.
• Reenvía el token mediante el encabezado X-Qonto-Sca-Session-Token.

Esta es la ruta utilizada en el paso (2) del recurso de dos pasos. También es útil cuando el cliente LLM implementa su propia cadencia de consulta y solo necesita que el wrapper reintente con una aprobación ya capturada.

Pruebas en sandbox

Las cuentas sandbox no pueden inscribir un dispositivo emparejado real, por lo que los desafíos SCA en sandbox usan un flujo de mock. Después de recibir una respuesta pendiente, simula la decisión del usuario con la herramienta sca_session_mock_decision (solo sandbox: se niega a ejecutarse cuando no hay un token de staging configurado). Consulta docs/sandbox-testing.md para la configuración completa del sandbox.

Nota de migración

Las versiones anteriores de QontoCtl (precontinuación SCA @qontoctl/mcp) devolvían una respuesta de texto de formato libre en 428 sin enlaces de continuación. Los llamadores que analizan esa respuesta deben adoptar el flujo estructurado:

El formato textual de la respuesta pendiente es estable, por lo que los llamadores que necesitan extraer el token programáticamente pueden buscar la línea Session token: — pero usar sca_session_show directamente evita depender de la prosa de la respuesta.

Uso de CLI

Primer comando para probar cuando algo no funciona: qontoctl diagnose — una verificación de salud de solo lectura en configuración, credenciales, alcances, metadatos de organización y enrutamiento del host.

Comandos

Opciones Globales

Configuración

QontoCtl admite dos métodos de autenticación:

• Clave API — acceso solo de producción usando tu slug de organización y clave secreta. Admite los endpoints listados como "API key ✔" en la tabla de autenticación de Qonto (la mayoría de lecturas y muchas escrituras: transferencias internas, clientes, adjuntos, …). No se puede usar contra el sandbox de Qonto.
• OAuth 2.0 — acceso completo, incluidos los endpoints solo OAuth (tarjetas, equipos, webhooks, facturación electrónica, enlaces de pago, seguros, transferencias internacionales, transferencias recurrentes, flujos SCA) y el sandbox de Qonto mediante staging-token; consulta la Guía de configuración de la aplicación OAuth.

Formato de perfil

Todos los archivos de configuración usan el mismo formato YAML:

# API Key authentication
api-key:
    organization-slug: acme-corp-4821
    secret-key: your-secret-key

# OAuth 2.0 authentication (see docs/oauth-setup.md)
oauth:
    client-id: your-client-id
    client-secret: your-client-secret

Orden de resolución

La CLI resuelve el archivo de configuración en este orden (mayor prioridad primero):

1. Bandera --config <path>
2. Variable de entorno QONTOCTL_CONFIG_FILE
3. ~/.qontoctl/{name}.yaml (cuando se proporciona --profile <name>)
4. ~/.qontoctl.yaml (predeterminado del directorio de inicio)

Cuando se suministra --config junto con QONTOCTL_CONFIG_FILE o --profile y las rutas resueltas no coinciden, --config gana y se emite una advertencia en stderr para que la anulación sea visible.

Sin descubrimiento en el directorio actual. La CLI no escanea el directorio de trabajo en busca de .qontoctl.yaml. Para configuración local del repositorio, usa un shim direnv que exporte QONTOCTL_CONFIG_FILE="$PWD/.qontoctl.yaml", o pasa --config ./.qontoctl.yaml explícitamente en cada invocación.

Las anulaciones por campo se aplican además del archivo cargado:

• Sin --profile: las variables de entorno QONTOCTL_* anulan los valores del archivo
• Con --profile acme: las variables de entorno QONTOCTL_ACME_* anulan los valores del archivo

Para la referencia completa (reglas de precedencia por punto de entrada, semántica de perfiles, migración desde el descubrimiento CWD), consulta docs/configuration.md.

Variables de entorno

Las variables de entorno anulan los valores del archivo. Transportan entradas (configuración estática) que la herramienta lee pero nunca escribe de vuelta; el estado mutable en tiempo de ejecución (tokens de actualización, expiración de tokens, alcances otorgados) vive solo en el archivo. Consulta la nota sobre QONTOCTL_ACCESS_TOKEN a continuación.

Sin --profile:

Con --profile <name>, el prefijo se convierte en QONTOCTL_{NAME}_ (en mayúsculas, con guiones reemplazados por guiones bajos). Por ejemplo, --profile acme lee QONTOCTL_ACME_ORGANIZATION_SLUG.

Semántica de QONTOCTL_ACCESS_TOKEN: cuando se establece, el portador suministrado por entorno se usa solo para la invocación actual. No se intenta la actualización proactiva del token, y los tokens actualizados no se persisten en disco (refleja AWS_SESSION_TOKEN). Si el token ha expirado, la API muestra un 401; vuelve a emitir el token externamente.

QONTOCTL_REFRESH_TOKEN no se admite intencionalmente. Los tokens de actualización son estado mutable en tiempo de ejecución — cada actualización produce un nuevo valor que la herramienta debe escribir en algún lugar — y las variables de entorno transportan entradas, no estado. Usa credenciales basadas en archivos (~/.qontoctl.yaml o un perfil) para flujos OAuth que necesiten actualización, o quédate con variables de entorno de clave API en CI.

Modo de depuración

Las banderas --verbose y --debug habilitan el registro a nivel de cable en stderr:

qontoctl --verbose transaction list   # request/response summaries
qontoctl --debug transaction list     # full headers and response bodies

Nota de seguridad: --debug registra cuerpos completos de respuestas de API. Los campos sensibles conocidos (IBAN, BIC, saldo) se redactan automáticamente, pero las respuestas pueden contener aún otros datos financieros. No uses --debug en entornos compartidos ni canalices la salida de depuración a archivos accesibles por otros.

Descargo de responsabilidad

qontoctl es un proyecto independiente no afiliado, respaldado ni conectado oficialmente a Qonto. Se ejecuta en tu propia máquina con tus propias credenciales.

"Qonto" y el logotipo de Qonto son marcas comerciales de Olinda SAS (la empresa que opera Qonto); qontoctl usa el nombre solo para describir el servicio con el que interoperan.

Licencia

AGPL-3.0-only

Qué significa AGPL para ti

• Usar qontoctl como herramienta CLI o servidor MCP no hace que tu código tenga licencia AGPL. Ejecutar la herramienta, escribir scripts a su alrededor o conectarla a tus aplicaciones es uso normal — no surgen obligaciones de licencia.
• Usar @qontoctl/core como biblioteca (importándola en tu código) significa que tu trabajo combinado está cubierto por AGPL-3.0. Si distribuyes ese trabajo combinado, debes poner su código fuente a disposición bajo términos compatibles con AGPL.
• Modificar y distribuir qontoctl en sí requiere que compartas tus cambios bajo AGPL-3.0.
• Licencias comerciales están disponibles si AGPL no se ajusta a tu caso de uso — contacta al mantenedor.