Conta Azul MCP

Conta Azul MCP

ERP financiero Conta Azul para Claude, Cursor y agentes de IA

Conecta tu cuenta Conta Azul a tu agente de IA. Gestiona clientes y proveedores, productos, servicios, ventas, contratos, cuentas por pagar y por cobrar, cuotas, liquidaciones y NF-e en lenguaje natural. Inicio de sesión vía OAuth de la propia Conta Azul, en 30 segundos — sin escribir token, sin configurar nada.

• 🏢 ERP completo — personas, productos, ventas, contratos, finanzas y NF-e en un solo lugar
• 💬 Funciona con cualquier cliente MCP: Claude Desktop, Cursor, VS Code, Cline, Continue
• ✍️ Lee y escribe — la IA consulta datos y también crea/edita registros, ventas, cuentas y liquidaciones (siempre cuando tú lo pides)
• 📊 35 herramientas que cubren la API v2 de Conta Azul
• 🔑 OAuth 2.0 de Conta Azul — la plataforma proporciona la aplicación OAuth, solo haces clic en Autorizar
• 🛡️ Cumple con la LGPD — consentimiento explícito, retención mínima, tú tienes el control

Versión en inglés · Documentación completa · Skills de Claude Code

Instalar en 1 clic

Claude (Web y Desktop)

Anthropic unificó la instalación de MCPs en claude.ai/customize/connectors. El mismo enlace sirve para Claude Web y Claude Desktop (solo necesitas estar conectado a tu cuenta):

➕ Abrir en Claude y conectar

Ese enlace abre el modal "Agregar conector personalizado" ya con nombre (Conta Azul MCP) y URL (https://api.mcp.ai/contaazul) prellenados. Haz clic en Agregar, inicia sesión vía magic-link en la primera llamada, autoriza tu empresa Conta Azul.

Manual (si el deeplink no se abre): ve a claude.ai/customize/connectors → haz clic en + → Agregar conector personalizado → pega:

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

Cursor

➕ Instalar Conta Azul MCP en Cursor

VS Code (Copilot Chat)

➕ Instalar Conta Azul MCP en VS Code

ChatGPT, Manus, OpenClaw y más de 40+ clientes

Conta Azul MCP funciona en cualquier cliente MCP que soporte MCP over HTTP. La URL del servidor es siempre la misma:

https://api.mcp.ai/contaazul

Consulta INSTALL.md para ejemplos de configuración por cliente.

Instrucciones detalladas: INSTALL.md — configuración manual en archivo (claude_desktop_config.json, .cursor/mcp.json, .vscode/mcp.json), flujo agent-auth para clientes sin OAuth, solución de problemas, e instrucciones para que la IA te ayude a instalar.

Prompt listo para agentes autónomos (OpenClaw, Hermes, etc.)

Algunos agentes autónomos tratan MCP como proceso local (stdio/npx) o se detienen en la etapa de "registrar en el config" sin nunca llamar a las tools. Pega el prompt a continuación para forzar el consumo correcto como MCP remoto HTTP y ejecutar el flujo de autenticación de principio a fin:

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.

Pregunta sobre tu negocio

Después de autorizar tu empresa, haz preguntas y da 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

✍️ Lee y escribe: además de consultar, la IA puede crear y modificar datos en tu Conta Azul — registros, ventas, contratos, cuentas por pagar/cobrar y liquidaciones. Las escrituras solo ocurren cuando tú lo pides. Recomendamos revisar la acción propuesta antes de confirmar (especialmente cancelaciones y eliminaciones, que son destructivas).

35 herramientas disponibles

Cubren la API v2 de Conta Azul, organizadas por módulo. Detalle de cada una en docs/ferramentas.md.

Empresa y cuentas

Personas (clientes / proveedores / vendedores / transportistas)

Productos y servicios

Ventas

Contratos

Financiero (cuentas por cobrar / pagar / cuotas / liquidación)

NF-e

Documentación detallada de cada tool: docs/ferramentas.md

Lo que se puede hacer

Conta Azul MCP cubre los principales módulos del ERP:

• Personas — clientes, proveedores, vendedores y transportistas (listar, detallar, crear, actualizar, eliminar)
• Productos y servicios — catálogo de productos y servicios con precio de venta
• Ventas — listar, detallar, crear, actualizar y cancelar ventas
• Contratos — contratos recurrentes (crear, consultar, cancelar)
• Cuentas por cobrar / pagar — listar y crear asientos financieros
• Cuotas y liquidaciones — listar cuotas, liquidar (settle) y deshacer liquidación (unsettle)
• Cuentas financieras — bancos, caja, tarjetas
• Categorías (DRE) y centros de costo — taxonomía financiera para análisis
• NF-e — consulta de notas fiscales electrónicas emitidas

Cómo 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

Una autorización = una empresa Conta Azul. Los planes superiores permiten conectar más de una empresa.

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

Skill para agentes de IA

Una skill general que cubre todos los casos de uso de Conta Azul MCP — ventas, facturación, cuentas por pagar/cobrar, flujo de caja, registros, contratos y NF-e. Funciona en Claude Code, Cursor, Codex, OpenCode y otros 50+ agentes soportados por el ecosistema skills.sh.

Instalar vía 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/

📁 Contenido de la skill: skills/contaazul-mcp/SKILL.md

Después solo pide cosas como "Resume mi flujo de caja del mes" o "Registra este nuevo cliente" — la skill se activa automáticamente y orquesta las 35 tools de Conta Azul MCP.

Precios

Planos PJ (CNPJ). Cobro en R$ (BRL), mensual.

Detalle: docs/precos.md. Cancela cuando quieras, sin cargo.

Privacidad y LGPD

• Consentimiento explícito vía OAuth de Conta Azul, revocable en cualquier momento
• Alcance mínimo: solo los datos de la(s) empresa(s) Conta Azul que autorices
• Lee y escribe: la IA puede consultar y también crear/modificar datos — siempre cuando tú lo pides
• Retención mínima: datos de una empresa eliminados después de desconectar
• Sub-procesadores: Conta Azul (ERP) + LLM host que elijas
• Tú tienes el control: revocar la autorización OAuth, exportar datos, eliminar cuenta

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

⚠️ Atención: los datos devueltos por las tools se envían al LLM host que elijas (Anthropic / OpenAI / Cursor / agente propio). Ese proveedor es sub-procesador fuera de nuestro control. Recomendamos contratar planes con opt-out de entrenamiento activado.

Preguntas frecuentes

¿Puede la IA modificar datos en mi Conta Azul? Sí. A diferencia de un MCP de solo lectura, Conta Azul MCP tiene herramientas de escritura: crear/actualizar personas, productos y servicios; crear/actualizar/cancelar ventas y contratos; crear cuentas por pagar/cobrar; liquidar y deshacer liquidaciones. Las escrituras solo ocurren cuando tú lo pides al agente. Las operaciones destructivas (cancelar venta/contrato, eliminar persona) deben revisarse antes de confirmar — el token da acceso completo a la empresa autorizada.

¿Necesito entregar mi contraseña de Conta Azul? No. La conexión es vía OAuth 2.0 de la propia Conta Azul — inicias sesión en el sitio oficial de Conta Azul y autorizas el acceso. Tu contraseña nunca pasa por nosotros.

¿Se usan mis datos para entrenar IA? No por nosotros. Los datos van al LLM host que elijas (Claude, ChatGPT, etc.) — la política de entrenamiento es responsabilidad del proveedor de IA. Recomendamos opt-out.

¿Puedo conectar más de una empresa? Sí. Cada autorización OAuth conecta una empresa Conta Azul. Los planes Plus (hasta 3) y Unlimited (5+) permiten múltiples empresas — útil para contadores y grupos.

¿Cómo cancelo? app.mcp.ai/contaazul → Settings → Assinatura → Cancelar. Termina al final del ciclo, sin cargo.

¿Puedo usar con agente propio (no Claude/Cursor)? Sí — cualquier cliente que soporte MCP over HTTP. Consulta INSTALL.md sección "Otros clientes".

¿El servidor es open source? El servidor es propietario (hosted). Este repositorio es el wrapper público con manifiestos, docs y skills — todo MIT. PRs y contribuciones en docs/skills son bienvenidas.

Contribuyendo

Issues, PRs y sugerencias son bienvenidos. Especialmente:

• Traducciones de docs/skills (EN ✓, ES, FR, IT)
• Nuevas skills de Claude Code
• Snippets de instalación para clientes MCP nuevos
• Correcciones/mejoras en la documentación

Por favor lee SECURITY.md antes de abrir un issue con algo relacionado a seguridad.

Soporte

• 📧 contaazul@mcp.ai — dudas, sugerencias, alianzas
• 🐛 GitHub Issues — bugs y features
• 📄 docs/ — documentación completa en PT-BR

Licencia

MIT — consulta LICENSE.

El servidor MCP en api.mcp.ai/contaazul es propietario (hosted). Este repositorio (manifiestos, docs, skills) es MIT.

Conta Azul es marca de Conta Azul. Este proyecto no está afiliado a Conta Azul — usa la API v2 pública vía OAuth 2.0.