Conta Azul MCP Server

Conta Azul MCP

ERP financeiro Conta Azul para Claude, Cursor e agentes de IA

Conecte sua conta Conta Azul ao seu agente de IA. Gerencie clientes e fornecedores, produtos, serviços, vendas, contratos, contas a pagar e receber, parcelas, quitações e NF-e em linguagem natural. Login via OAuth da própria Conta Azul, em 30 segundos — sem digitar token, sem configurar nada.

• 🏢 ERP completo — pessoas, produtos, vendas, contratos, financeiro e NF-e em um só lugar
• 💬 Funciona com qualquer cliente MCP: Claude Desktop, Cursor, VS Code, Cline, Continue
• ✍️ Lê e escreve — a IA consulta dados e também cria/edita cadastros, vendas, contas e quitações (sempre quando você pede)
• 📊 35 ferramentas cobrindo a API v2 da Conta Azul
• 🔑 OAuth 2.0 da Conta Azul — a plataforma fornece a aplicação OAuth, você só clica em Autorizar
• 🛡️ LGPD-compliant — consentimento explícito, retenção mínima, você no controle

English version · Documentação completa · Skills do Claude Code

Instalar em 1 clique

Claude (Web e Desktop)

A Anthropic unificou a instalação de MCPs em claude.ai/customize/connectors. O mesmo link serve pra Claude Web e Claude Desktop (basta estar logado na sua conta):

➕ Abrir no Claude e conectar

Esse link abre o modal "Adicionar conector personalizado" já com nome (Conta Azul MCP) e URL (https://api.mcp.ai/contaazul) pré-preenchidos. Clique Adicionar, faça login via magic-link na primeira chamada, autorize sua empresa Conta Azul.

Manual (se o deeplink não abrir): vá em claude.ai/customize/connectors → clique + → Adicionar conector personalizado → cole:

• Nome: Conta Azul MCP
• URL: https://api.mcp.ai/contaazul

Cursor

➕ Instalar Conta Azul MCP no Cursor

VS Code (Copilot Chat)

➕ Instalar Conta Azul MCP no VS Code

ChatGPT, Manus, OpenClaw e mais 40+ clientes

Conta Azul MCP funciona em qualquer cliente MCP que suporte MCP over HTTP. A URL do servidor é sempre a mesma:

https://api.mcp.ai/contaazul

Veja INSTALL.md pra exemplos de configuração por cliente.

Instruções detalhadas: INSTALL.md — config manual em arquivo (claude_desktop_config.json, .cursor/mcp.json, .vscode/mcp.json), fluxo agent-auth pra clientes sem OAuth, troubleshooting, e instruções pra IA te ajudar a instalar.

Prompt pronto pra agents autônomos (OpenClaw, Hermes, etc.)

Alguns agents autônomos tratam MCP como processo local (stdio/npx) ou param na etapa de "registrar no config" sem nunca chamar as tools. Cole o prompt abaixo pra forçar o consumo correto como MCP remoto HTTP e rodar o fluxo de autenticação de ponta a ponta:

Use o Conta Azul MCP (ERP financeiro brasileiro, API v2 da Conta Azul) como um servidor MCP externo remoto via HTTP. Não trate esse MCP como local, não use stdio, não execute npx, node, subprocesso para "subir" servidor, e não assuma que apenas registrar a URL em config é suficiente. O endpoint é https://api.mcp.ai/contaazul e deve ser consumido por MCP remoto via HTTP/streamable-http. A prioridade é: (1) se o ambiente tiver suporte nativo a cliente MCP remoto HTTP, use-o; (2) se não tiver, procure um cliente MCP HTTP externo já disponível no próprio ambiente/servidor e use-o para conectar ao endpoint e chamar as tools; (3) só declare limitação depois de tentar ambos os caminhos. O objetivo é realmente consumir o MCP remoto, não apenas cadastrá-lo. Primeiro, se o ambiente usar registro/config de MCP, registre o servidor com nome como contaazul-mcp, URL https://api.mcp.ai/contaazul e transporte streamable-http; em seguida, teste conectividade real ao endpoint remoto. Antes de qualquer autenticação, liste as ferramentas disponíveis no servidor remoto; como o Conta Azul MCP é soft-gate, a descoberta inicial (mesmo deslogado) deve retornar TODAS as ferramentas do ERP — contaazul_list_accounts, contaazul_get_company, contaazul_list_people, contaazul_list_sales, contaazul_list_receivables, contaazul_list_payables, contaazul_list_invoices_nfe e demais contaazul_* — além de show_version, report_bug, connect e authenticate. Se a listagem funcionar, prossiga obrigatoriamente com o fluxo. O fluxo correto é: 1. chamar a tool authenticate sem argumentos (ou chamar qualquer tool contaazul_* deslogado, que retornará o link de autenticação); 2. se retornar um link de login, mostrar esse link ao usuário e instruí-lo a abrir, autenticar no mcp.ai e enviar o token retornado; 3. quando o usuário enviar o token, chamar authenticate novamente com { "token": "<jwt_enviado_pelo_usuario>" }; 4. após autenticação confirmada, chamar connect; 5. se connect retornar um link de autorização da Conta Azul (OAuth 2.0), mostrar ao usuário para abrir, logar na conta Conta Azul dele e autorizar o acesso à empresa; 6. depois da conexão, usar as tools de consulta contaazul_list_accounts, contaazul_get_company, contaazul_list_sales, contaazul_list_people, contaazul_list_receivables, contaazul_list_payables e contaazul_list_invoices_nfe para ler os dados do ERP. O Conta Azul MCP também tem ferramentas de escrita (criar/atualizar pessoas, produtos, vendas, contratos, contas a pagar/receber, quitar parcelas) — só use escrita quando o usuário pedir explicitamente, e confirme antes de operações destrutivas (cancelar venda/contrato, excluir pessoa). O assistente deve ser operacional: não parar na etapa de config se houver um modo de realmente chamar tools no ambiente; não pedir instalação de SDK sem necessidade; não dizer que "não é possível" sem antes verificar suporte nativo MCP remoto e, na falta dele, a existência de cliente MCP HTTP externo já presente no ambiente. Se o ambiente exigir reinício, reload de serviço ou reaplicação de configuração para usar o MCP, avise o usuário antes, com mensagem clara como: "Vou reiniciar para aplicar a configuração do Conta Azul MCP — volto em instantes." Depois confirme que voltou. Se não precisar reiniciar, não mencione reinício. Ao receber um link de autenticação de authenticate, responda objetivamente com algo como: "Abra este link, faça login no mcp.ai e me envie o token que aparecer: <link>". Em resumo: trate o Conta Azul MCP como MCP remoto HTTP, tente conexão real, liste tools, execute authenticate, peça o token ao usuário, execute authenticate com token, depois execute connect, peça a autorização OAuth na Conta Azul e então use as tools contaazul_* para consultar (e, quando o usuário pedir, gerenciar) os dados do ERP.

Pergunte sobre o seu negócio

Depois de autorizar sua empresa, faça perguntas e dê comandos como:

Liste as 20 últimas vendas e o total faturado nos últimos 30 dias
Quais contas a pagar vencem essa semana?
Quais contas a receber estão vencidas hoje?
Cadastra o cliente João Silva (CPF 123.456.789-00, e-mail [email protected])
Cria um produto "Setup Inicial" com valor de venda R$ 499
Registra uma venda do produto Mensalidade Premium para o cliente X
Resume meu fluxo de caixa do mês (entradas vs saídas)
Quita a parcela de R$ 250 que venceu hoje na conta do Itaú
Lista as NF-e emitidas em maio

✍️ Lê e escreve: além de consultar, a IA pode criar e alterar dados na sua Conta Azul — cadastros, vendas, contratos, contas a pagar/receber e quitações. As escritas só acontecem quando você pede. Recomendamos revisar a ação proposta antes de confirmar (especialmente cancelamentos e exclusões, que são destrutivos).

35 ferramentas disponíveis

Cobrem a API v2 da Conta Azul, organizadas por módulo. Detalhe de cada uma em docs/ferramentas.md.

Empresa & contas

Pessoas (clientes / fornecedores / vendedores / transportadores)

Produtos & serviços

Vendas

Contratos

Financeiro (contas a receber / pagar / parcelas / quitação)

NF-e

Documentação detalhada de cada tool: docs/ferramentas.md

O que dá pra fazer

Conta Azul MCP cobre os principais módulos do ERP:

• Pessoas — clientes, fornecedores, vendedores e transportadores (listar, detalhar, criar, atualizar, remover)
• Produtos & serviços — catálogo de produtos e serviços com preço de venda
• Vendas — listar, detalhar, criar, atualizar e cancelar vendas
• Contratos — contratos recorrentes (criar, consultar, cancelar)
• Contas a receber / pagar — listar e criar lançamentos financeiros
• Parcelas & quitações — listar parcelas, quitar (settle) e desfazer quitação (unsettle)
• Contas financeiras — bancos, caixa, cartões
• Categorias (DRE) & centros de custo — taxonomia financeira pra análises
• NF-e — consulta de notas fiscais eletrônicas emitidas

Como funciona

1. Você instala o MCP no seu cliente (Claude/Cursor/VS Code)
2. Na primeira chamada, browser abre pra magic-link
3. Você cria conta (só e-mail, sem senha) e clica em "Autorizar com Conta Azul"
4. Loga na sua conta Conta Azul (OAuth 2.0) e autoriza a empresa
5. Pronto — comandos e perguntas em linguagem natural

Uma autorização = uma empresa Conta Azul. Planos superiores permitem conectar mais de uma empresa.

Detalhe técnico: docs/instalacao.md · docs/autenticacao.md

Skill pra agentes de IA

Uma skill geral que cobre todos os casos de uso do Conta Azul MCP — vendas, faturamento, contas a pagar/receber, fluxo de caixa, cadastros, contratos e NF-e. Funciona em Claude Code, Cursor, Codex, OpenCode e outros 50+ agentes suportados pelo ecossistema skills.sh.

Instalar via skills.sh (recomendado)

# detecta seu agente automaticamente e instala no diretório certo
npx skills add douglac/contaazul-mcp

# ou instala globalmente (todos os projetos)
npx skills add douglac/contaazul-mcp -g

# pra um agente específico
npx skills add douglac/contaazul-mcp -a claude-code

Instalar manualmente (Claude Code)

cp -r skills/contaazul-mcp ~/.claude/skills/

📁 Conteúdo da skill: skills/contaazul-mcp/SKILL.md

Depois é só pedir coisas como "Resume meu fluxo de caixa do mês" ou "Cadastra esse novo cliente" — a skill ativa automaticamente e orquestra as 35 tools do Conta Azul MCP.

Preços

Planos PJ (CNPJ). Cobrança em R$ (BRL), mensal.

Detalhamento: docs/precos.md. Cancela quando quiser, sem taxa.

Privacidade & LGPD

• Consentimento explícito via OAuth da Conta Azul, revogável a qualquer momento
• Escopo mínimo: só os dados da(s) empresa(s) Conta Azul que você autorizar
• Lê e escreve: a IA pode consultar e também criar/alterar dados — sempre quando você pede
• Retenção mínima: dados de uma empresa apagados após desconectar
• Sub-processadores: Conta Azul (ERP) + LLM host que você escolher
• Você no controle: revogar a autorização OAuth, exportar dados, excluir conta

Política completa: docs/privacidade-lgpd.md

⚠️ Atenção: os dados retornados pelas tools são enviados ao LLM host que você escolher (Anthropic / OpenAI / Cursor / agente próprio). Esse provedor é sub-processador fora do nosso controle. Recomendamos contratar planos com opt-out de treinamento ativado.

Perguntas frequentes

A IA pode alterar dados na minha Conta Azul? Sim. Diferente de um MCP só-leitura, o Conta Azul MCP tem ferramentas de escrita: criar/atualizar pessoas, produtos e serviços; criar/atualizar/cancelar vendas e contratos; criar contas a pagar/receber; quitar e desfazer quitações. As escritas só ocorrem quando você pede ao agente. Operações destrutivas (cancelar venda/contrato, excluir pessoa) devem ser revisadas antes de confirmar — o token dá acesso completo à empresa autorizada.

Preciso entregar minha senha da Conta Azul? Não. A conexão é via OAuth 2.0 da própria Conta Azul — você loga no site oficial da Conta Azul e autoriza o acesso. Sua senha nunca passa pela gente.

Meus dados são usados pra treinar IA? Não pela gente. Os dados vão pro LLM host que você escolher (Claude, ChatGPT, etc.) — política de treinamento é responsabilidade do provedor de IA. Recomendamos opt-out.

Posso conectar mais de uma empresa? Sim. Cada autorização OAuth conecta uma empresa Conta Azul. Os planos Plus (até 3) e Unlimited (5+) permitem múltiplas empresas — útil pra contadores e grupos.

Como cancelo? app.mcp.ai/contaazul → Settings → Assinatura → Cancelar. Encerra no fim do ciclo, sem taxa.

Posso usar com agente próprio (não Claude/Cursor)? Sim — qualquer cliente que suporte MCP over HTTP. Veja INSTALL.md seção "Outros clientes".

O servidor é open source? O servidor é proprietário (hosted). Este repositório é o wrapper público com manifestos, docs e skills — tudo MIT. PRs e contribuições nas docs/skills são bem-vindas.

Contribuindo

Issues, PRs e sugestões são bem-vindas. Especialmente:

• Traduções de docs/skills (EN ✓, ES, FR, IT)
• Novas skills do Claude Code
• Snippets de instalação pra clientes MCP novos
• Correções/melhorias na documentação

Por favor leia SECURITY.md antes de abrir issue com algo relacionado a segurança.

Suporte

• 📧 [email protected] — dúvidas, sugestões, parcerias
• 🐛 GitHub Issues — bugs e features
• 📄 docs/ — documentação completa em PT-BR

Licença

MIT — veja LICENSE.

O servidor MCP em api.mcp.ai/contaazul é proprietário (hosted). Este repositório (manifestos, docs, skills) é MIT.

Conta Azul é marca da Conta Azul. Este projeto não é afiliado à Conta Azul — usa a API v2 pública via OAuth 2.0.