QontoCtl

CLI e servidor MCP para a API bancária do Qonto.

Este projeto é oferecido por Alexey Pelykh.

Projeto não oficial. O QontoCtl é independente e não é afiliado, endossado ou suportado pela Qonto. Consulte o Aviso Legal.

O Que Ele Faz

O QontoCtl permite que assistentes de IA (Claude, etc.) interajam com a Qonto por meio do Model Context Protocol. Ele pode:

• Organizações — recuperar detalhes e configurações da organização
• Contas — listar, criar, atualizar, fechar contas bancárias; baixar certificados IBAN
• Transações — listar, pesquisar, filtrar transações bancárias; gerenciar anexos de transações
• Extratos Bancários — listar, visualizar e baixar extratos bancários
• Etiquetas — gerenciar etiquetas e categorias de transações
• Associações — visualizar membros da equipe, mostrar associação atual, convidar novos membros
• Beneficiários SEPA — listar, adicionar, atualizar, confiar/não confiar em beneficiários SEPA
• Transferências SEPA — listar, criar, cancelar transferências; baixar comprovantes; verificar beneficiários
• Transferências Internas — criar transferências entre contas da mesma organização
• Transferências em Lote — listar, visualizar e criar lotes de transferências SEPA em massa
• Transferências Recorrentes — listar, visualizar, criar, cancelar transferências recorrentes
• Transferências Internacionais (SWIFT) — criar transferências SWIFT e gerenciar beneficiários internacionais
• Cartões — listar, criar, atualizar, bloquear/desbloquear, reportar perdido/roubado, descartar cartões
• Equipes — listar e criar equipes
• Webhooks — criar e gerenciar assinaturas de webhook
• Links de Pagamento — criar, desativar e gerenciar links de pagamento com suporte Stripe
• Seguros — mostrar, criar, atualizar contratos de seguro e gerenciar documentos
• Terminais (POS) — listar Terminais Qonto e iniciar pagamentos de terminal
• Produtos — listar produtos do catálogo
• Clientes — listar, criar, atualizar, excluir clientes
• Faturas de Clientes — ciclo de vida completo: criar, atualizar, finalizar, enviar, marcar como paga, cancelar, enviar arquivos
• Cotações — criar, atualizar, excluir, enviar cotações
• Notas de Crédito — listar e visualizar notas de crédito
• Faturas de Fornecedores — listar, visualizar e criar em massa faturas de fornecedores
• Solicitações — listar solicitações da organização
• Anexos — enviar e visualizar anexos
• Faturamento Eletrônico — recuperar configurações de faturamento eletrônico

QontoCtl e o MCP oficial da Qonto

O QontoCtl é um projeto independente e não oficial — não afiliado ou endossado pela Qonto.

A Qonto oferece seu próprio servidor MCP oficial — hospedado, gratuito em todos os planos e instalável com um toque a partir do Claude, ChatGPT, Cursor e outros. Se você quiser conversar com suas finanças — "mostrar meus saldos", "gráfico dos gastos do mês passado", "rascunhar uma fatura" — é uma opção excelente e bem feita.

O QontoCtl foi criado para uma tarefa diferente: automatizar a Qonto, não apenas conversar com ela.

O MCP oficial é um assistente hospedado no qual você faz login como usuário. O QontoCtl é um kit de ferramentas local e de código aberto — um CLI, um servidor MCP e uma biblioteca — que roda na sua própria máquina com suas próprias credenciais, inclusive como conta de serviço headless.

_{Comparação baseada na documentação pública do MCP da Qonto em julho de 2026.}

_{* Transferências para beneficiários não confiáveis ainda exigem sua aprovação de Autenticação Forte do Cliente, como devem. O QontoCtl lida com a continuação do SCA para que fluxos scriptados — para beneficiários confiáveis e entre suas próprias contas — sejam concluídos sem um humano no terminal.}

O QontoCtl também suporta múltiplas organizações Qonto a partir de uma única configuração por meio de perfis nomeados — útil para contadores, holdings e qualquer pessoa que gerencie as contas de várias entidades.

O MCP oficial conversa com a Qonto. O QontoCtl automatiza. Muitas pessoas usarão ambos — o MCP oficial em uma janela de chat, o QontoCtl em um pipeline.

Pré-requisitos

• Node.js >= 24
• Uma conta empresarial Qonto com acesso à API

Instalação

npm install -g qontoctl

Ou execute diretamente com npx:

npx qontoctl --help

Ou instale via Homebrew:

brew install qontoctl/tap/qontoctl

Início 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

Integração MCP

O QontoCtl implementa o Model Context Protocol (MCP), permitindo que assistentes de IA interajam com sua conta Qonto por meio de linguagem natural.

Configuração do 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"]
        }
    }
}

Apontando o MCP para um arquivo de configuração não padrão

O servidor MCP não possui flags de CLI. Para carregar credenciais de um arquivo de configuração diferente de ~/.qontoctl.yaml, defina QONTOCTL_CONFIG_FILE no bloco env do host:

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

O caminho é capturado na inicialização do servidor. Consulte docs/configuration.md para a cadeia completa de resolução.

Ferramentas MCP Disponíveis

Exemplos de Prompts

Depois de configurado, você pode perguntar ao seu assistente de IA coisas como:

• "Mostre meus saldos de contas Qonto"
• "Liste transações recentes acima de 1000 EUR"
• "Quais foram os pagamentos com cartão do mês passado?"
• "Mostre todos os membros da equipe na minha organização"
• "Liste extratos bancários de janeiro de 2026"
• "Crie um resumo dos débitos desta semana"

Continuação SCA

Algumas operações de escrita da Qonto — criar uma transferência, modificar um cartão, aprovar uma solicitação — exigem Autenticação Forte do Cliente (SCA): o usuário precisa aprovar a solicitação no aplicativo móvel da Qonto antes que ela seja executada. O QontoCtl envolve cada ferramenta de escrita MCP protegida por SCA com um fluxo de continuação para que o cliente LLM nunca precise reimplementar a sondagem.

Como uma ferramenta envolvida se comporta

Quando uma ferramenta protegida por SCA (ex.: transfer_create, card_create, beneficiary_trust, request_approve) encontra um desafio SCA 428, o wrapper sonda a sessão SCA inline. Se o usuário aprovar dentro da janela de sondagem, a ferramenta retorna o resultado de sucesso da operação de forma transparente — o LLM nunca vê o round-trip do SCA. Se a sondagem expirar (ou estiver desabilitada), a ferramenta retorna uma resposta estruturada de SCA pendente contendo o token da sessão e instruções para continuar.

Cada ferramenta envolvida expõe dois campos de entrada opcionais para este fluxo:

• wait — segundos máximos para sondar inline antes de cair para a resposta pendente.
• sca_session_token — vincula um desafio SCA previamente aprovado a uma nova tentativa.

O controle wait

O limite superior 120 é o teto rígido imposto via Zod na fronteira de entrada. O teto prático é o tempo limite de solicitação do seu host MCP — o Claude Desktop define ≈ 60 s e o limite efetivo do Cursor é ≈ 30 s, então valores acima desses aparecerão como timeouts do lado do host antes que o wrapper resolva. Use um wait pequeno (por exemplo, 5-10) quando o LLM espera que o usuário esteja presente e disposto a aprovar imediatamente. Use wait: false (ou wait: 0) para fluxos puros de duas etapas onde o LLM e o usuário conversam fora de banda entre o desafio SCA e a nova tentativa.

Fallback de duas etapas (continuação fora de banda)

Quando a consulta não resolve, a resposta pendente de SCA contém:

• Uma mensagem voltada ao usuário: "SCA required. The user must approve this operation on their Qonto mobile app."
• Uma linha Session token: <token> (validade do token: 15 minutos a partir da emissão).
• Instruções passo a passo para continuar.

O LLM (ou o usuário) pode então:

1. Consulte o status da sessão com a ferramenta sca_session_show, passando o token capturado. Ela retorna waiting, allow ou deny.
2. Tente novamente a ferramenta original assim que o status for allow, passando os mesmos parâmetros mais sca_session_token: "<token>". O wrapper invoca a operação exatamente uma vez com o token vinculado — nenhuma segunda consulta acontece.

Vinculação dinâmica PSD2. O token de sessão SCA está vinculado aos parâmetros originais da solicitação (valor, beneficiário). Reutilizar um token em uma operação diferente é rejeitado pela Qonto. Reemita um desafio SCA chamando a ferramenta original novamente sempre que os parâmetros precisarem mudar.

Nova tentativa fornecida pelo chamador (sca_session_token)

Quando sca_session_token está definido em uma ferramenta de escrita encapsulada, o wrapper:

• Invoca a operação exatamente uma vez.
• Pula a consulta completamente.
• Encaminha o token via o cabeçalho X-Qonto-Sca-Session-Token.

Este é o caminho usado pela etapa (2) do fallback de duas etapas. Também é útil quando o cliente LLM implementa sua própria cadência de consulta e só precisa que o wrapper tente novamente com uma aprovação já capturada.

Testes em sandbox

Contas sandbox não podem registrar um dispositivo pareado real, então desafios SCA em sandbox usam um fluxo mock. Após receber uma resposta pendente, simule a decisão do usuário com a ferramenta sca_session_mock_decision (somente sandbox — recusa-se a executar quando nenhum token de staging está configurado). Consulte docs/sandbox-testing.md para a configuração completa do sandbox.

Nota de migração

Versões anteriores do QontoCtl (pré-continuação SCA @qontoctl/mcp) retornavam uma resposta de texto livre no 428 sem ganchos de continuação. Chamadores que analisam essa resposta devem adotar o fluxo estruturado:

O formato textual da resposta pendente é estável, então chamadores que precisam extrair o token programaticamente podem corresponder à linha Session token: — mas usar sca_session_show diretamente evita depender da prosa da resposta.

Uso da CLI

Primeiro comando a tentar quando algo não funciona: qontoctl diagnose — uma verificação de saúde somente leitura em configuração, credenciais, escopos, metadados da organização e roteamento do host.

Comandos

Opções Globais

Configuração

O QontoCtl suporta dois métodos de autenticação:

• API Key — acesso exclusivo para produção usando o slug da sua organização e a chave secreta. Suporta os endpoints listados como "API key ✔" na tabela de autenticação do Qonto (a maioria das leituras e muitas escritas — transferências internas, clientes, anexos, …). Não pode ser usado contra o sandbox do Qonto.
• OAuth 2.0 — acesso completo, incluindo endpoints exclusivos de OAuth (cartões, equipes, webhooks, faturamento eletrônico, links de pagamento, seguros, transferências internacionais, transferências recorrentes, fluxos SCA) e o sandbox do Qonto via staging-token; consulte o Guia de Configuração do App OAuth.

Formato do Perfil

Todos os arquivos de configuração usam o mesmo 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

Ordem de Resolução

A CLI resolve o arquivo de configuração nesta ordem (maior prioridade primeiro):

1. Flag --config <path>
2. Variável de ambiente QONTOCTL_CONFIG_FILE
3. ~/.qontoctl/{name}.yaml (quando --profile <name> é fornecido)
4. ~/.qontoctl.yaml (padrão do diretório home)

Quando --config é fornecido junto com QONTOCTL_CONFIG_FILE ou --profile e os caminhos resolvidos divergem, --config vence e um aviso é emitido no stderr para que a substituição fique visível.

Sem descoberta no diretório atual. A CLI não verifica o diretório de trabalho em busca de .qontoctl.yaml. Para configuração local ao repositório, use um shim direnv que exporte QONTOCTL_CONFIG_FILE="$PWD/.qontoctl.yaml", ou passe --config ./.qontoctl.yaml explicitamente em cada invocação.

Substituições por campo são aplicadas sobre o arquivo carregado:

• Sem --profile: variáveis de ambiente QONTOCTL_* substituem os valores do arquivo
• Com --profile acme: variáveis de ambiente QONTOCTL_ACME_* substituem os valores do arquivo

Para a referência completa (regras de precedência por ponto de entrada, semântica de perfil, migração da descoberta CWD), consulte docs/configuration.md.

Variáveis de Ambiente

As variáveis de ambiente substituem os valores do arquivo. Elas carregam entradas (configuração estática) que a ferramenta lê, mas nunca grava de volta; o estado mutável em tempo de execução (tokens de atualização, expiração de token, escopos concedidos) vive apenas no arquivo. Consulte a nota sobre QONTOCTL_ACCESS_TOKEN abaixo.

Sem --profile:

Com --profile <name>, o prefixo torna-se QONTOCTL_{NAME}_ (em maiúsculas, hífens substituídos por sublinhados). Por exemplo, --profile acme lê QONTOCTL_ACME_ORGANIZATION_SLUG.

Semântica de QONTOCTL_ACCESS_TOKEN: quando definido, o bearer fornecido pelo ambiente é usado apenas para a invocação atual. A atualização proativa de token não é tentada, e tokens atualizados não são persistidos em disco (espelha AWS_SESSION_TOKEN). Se o token expirou, a API retorna um 401; reemita o token externamente.

QONTOCTL_REFRESH_TOKEN não é suportado intencionalmente. Tokens de atualização são estado mutável em tempo de execução — cada atualização produz um novo valor que a ferramenta precisa gravar em algum lugar — e variáveis de ambiente carregam entradas, não estado. Use credenciais baseadas em arquivo (~/.qontoctl.yaml ou um perfil) para fluxos OAuth que precisam de atualização, ou use variáveis de ambiente de chave de API em CI.

Modo de Depuração

As flags --verbose e --debug ativam o registro no nível de wire para o stderr:

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

Nota de segurança: --debug registra corpos completos de respostas da API. Campos sensíveis conhecidos (IBAN, BIC, saldo) são automaticamente mascarados, mas as respostas ainda podem conter outros dados financeiros. Não use --debug em ambientes compartilhados nem direcione a saída de depuração para arquivos acessíveis por outras pessoas.

Aviso Legal

qontoctl é um projeto independente não afiliado, endossado ou oficialmente conectado à Qonto. Ele é executado na sua própria máquina com suas próprias credenciais.

"Qonto" e o logotipo da Qonto são marcas registradas da Olinda SAS (a empresa que opera a Qonto); qontoctl usa o nome apenas para descrever o serviço com o qual interopera.

Licença

AGPL-3.0-only

O que AGPL significa para você

• Usar o qontoctl como ferramenta CLI ou servidor MCP não torna seu código licenciado sob AGPL. Executar a ferramenta, criar scripts em torno dela ou conectá-la aos seus aplicativos é uso normal — nenhuma obrigação de licença surge.
• Usar @qontoctl/core como biblioteca (importando-o no seu código) significa que seu trabalho combinado é coberto pela AGPL-3.0. Se você distribuir esse trabalho combinado, deve disponibilizar seu código-fonte sob termos compatíveis com AGPL.
• Modificar e distribuir o próprio qontoctl exige que você compartilhe suas alterações sob AGPL-3.0.
• Licenciamento comercial está disponível se a AGPL não se adequar ao seu caso de uso — entre em contato com o mantenedor.