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)
• 📊 52 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 joao@ex.com)
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).

---

52 ferramentas disponíveis

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

Empresa & contas

Tool	Descrição
contaazul_list_accounts	Lista as empresas Conta Azul vinculadas
contaazul_get_company	Dados da empresa ativa (CNPJ, razão social, regime tributário)

Pessoas (clientes / fornecedores / vendedores / transportadores)

Tool	Descrição
contaazul_list_people	Lista pessoas (filtros: busca, tipo, ativo)
contaazul_get_person	Detalhe de uma ou mais pessoas por id
contaazul_person_write_create	Cria uma pessoa
contaazul_person_write_update	Atualiza uma pessoa (só os campos enviados)
contaazul_person_delete	Remove pessoas (destrutivo)

Produtos & serviços

Tool	Descrição
contaazul_list_products	Lista produtos cadastrados
contaazul_product_write	Cria um produto
contaazul_list_services	Lista serviços cadastrados
contaazul_service_write	Cria um serviço

Vendas & orçamentos

Tool	Descrição
contaazul_list_sales	Lista vendas (filtros: cliente, vendedor, situação, categoria, produto, número, datas, texto livre)
contaazul_list_sale_items	Itens (produtos/serviços, quantidade, valor) de até 50 vendas
contaazul_get_sale	Detalhe de uma ou mais vendas por id
contaazul_sale_write_create	Cria uma venda
contaazul_sale_write_update	Atualiza uma venda
contaazul_sale_cancel	Cancela vendas (destrutivo)
contaazul_list_budgets	Lista orçamentos
contaazul_get_budget	Detalhe de um ou mais orçamentos por id
contaazul_create_budget	Cria um orçamento
contaazul_delete_budgets	Exclui orçamentos (destrutivo)

Contratos

Tool	Descrição
contaazul_list_contracts	Lista contratos por período
contaazul_get_contract	Detalhe de um ou mais contratos por id
contaazul_contract_next_number	Próximo número de contrato disponível
contaazul_contract_write	Cria um contrato
contaazul_terminate_contract	Encerra contratos
contaazul_delete_contract	Remove contratos (destrutivo)

Financeiro: contas a receber e a pagar

Tool	Descrição
contaazul_list_receivables	Lista contas a receber (filtros: vencimento, status)
contaazul_receivable_create	Cria uma conta a receber
contaazul_list_payables	Lista contas a pagar (filtros: vencimento, status)
contaazul_payable_create	Cria uma conta a pagar
contaazul_list_changed_events	Eventos financeiros alterados num período (sync incremental)

Financeiro: parcelas e baixas

Tool	Descrição
contaazul_list_installments	Parcelas de um evento financeiro
contaazul_get_installment	Detalhe de uma ou mais parcelas por id
contaazul_update_installment	Atualiza campos de uma parcela
contaazul_settle_installment	Registra a baixa (recebimento/pagamento) de uma parcela
contaazul_list_settlements	Lista as baixas de uma parcela
contaazul_get_settlement	Detalhe de uma baixa por id
contaazul_update_settlement	Atualiza uma baixa
contaazul_delete_settlement	Estorna uma baixa (destrutivo)

Cobranças

Tool	Descrição
contaazul_generate_charge	Gera boleto, Pix ou link de pagamento para parcelas
contaazul_get_charge	Detalhe de uma cobrança emitida
contaazul_cancel_charge	Cancela uma cobrança emitida

Contas financeiras, categorias e centros de custo

Tool	Descrição
contaazul_list_financial_accounts	Lista contas financeiras (banco, caixa, cartão)
contaazul_get_account_balance	Saldo atual de uma conta financeira
contaazul_get_initial_balance	Saldos iniciais das contas por período
contaazul_list_transfers	Transferências entre contas por período
contaazul_list_categories	Lista categorias financeiras (DRE)
contaazul_list_cost_centers	Lista centros de custo

Notas fiscais

Tool	Descrição
contaazul_list_invoices_nfe	Lista NF-e emitidas
contaazul_get_invoice_nfe	Detalhe de uma ou mais NF-e por id
contaazul_list_invoices_nfse	Lista NFS-e por competência

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, registrar baixa e estornar baixa
• 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 52 tools do Conta Azul MCP.

---

Preços

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

Plano	Preço	Empresas conectadas	Requests
Free	R$ 0	—	10 / 24h
Solo	R$ 19,90/mês	1	Ilimitados
Plus	R$ 29,90/mês	até 3	Ilimitados
Unlimited ⭐	R$ 49,90/mês	5+ (R$ 9/empresa extra)	Ilimitados

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

• 📧 contaazul@mcp.ai — 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.