Consulte CNPJ direto no Claude (e em qualquer IA) com servidor MCP

Existem duas peças que mudam a forma como você consulta CNPJ quando está construindo agentes ou usando IA no dia a dia: um servidor Model Context Protocol (MCP) e SDKs em Python e Node (TypeScript) para o cnpjaberto.com.br. Cada SDK também já traz o servidor MCP embutido, então dá pra usar do jeito que for mais natural pra sua stack: pip install cnpjaberto ou npx -y cnpjaberto. Qualquer pessoa pode usar agora mesmo.

A ideia é simples. O Claude Desktop, o Cursor, o Cline e outros clientes recentes de IA aceitam servidores MCP, que são programinhas locais que expõem ferramentas estruturadas ao modelo. Em vez de pedir pra IA "buscar na internet" o CNPJ de uma empresa e torcer pra ela acertar a fonte, você dá pra ela uma tool oficial: nome, parâmetros, retorno bem definido. O modelo passa a decidir por conta quando chamar lookup_cnpj, companies_by_owner, panorama_year, e por aí vai.

Por que isso importa

Hoje, quando alguém pergunta pro Claude "consulta o CNPJ 18.236.120/0001-58", o modelo tem três escolhas ruins. Pode chutar, pode pedir desculpas e dizer que não tem acesso, ou pode tentar buscar via web e cair em sites lentos cheios de captcha. Com o MCP do CNPJ Aberto rodando, ele simplesmente chama uma tool, recebe JSON estruturado em milissegundos e responde a pergunta com dados reais da Receita Federal.

Isso vale tanto pra uso pessoal (você no Claude Desktop tirando uma dúvida) quanto pra agentes que rodam em produção (validação de cadastro, due diligence, prospecção). A mesma stack serve os dois cenários porque o MCP é só um protocolo padrão por cima da API REST que já existe.

Em 60 segundos

Tem dois caminhos pra rodar o servidor MCP, escolhe o que combina com sua máquina.

Opção A: via Node (zero instalação prévia, recomendado se já tem Node 18+). Cola direto no config do Claude Desktop, em ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "cnpjaberto": {
      "command": "npx",
      "args": ["-y", "cnpjaberto"],
      "env": {
        "CNPJABERTO_API_KEY": "sua_chave_aqui"
      }
    }
  }
}

O npx -y cnpjaberto baixa o pacote do NPM sob demanda e roda o servidor; nada fica instalado globalmente.

Opção B: via Python (recomendado se Python já é a stack do dia). Instala uma vez:

pip install cnpjaberto[mcp]

E cola no mesmo arquivo de config:

{
  "mcpServers": {
    "cnpjaberto": {
      "command": "cnpjaberto-mcp",
      "env": {
        "CNPJABERTO_API_KEY": "sua_chave_aqui"
      }
    }
  }
}

Reinicia o Claude. Pronto. A partir daí pode perguntar coisas tipo:

• "Consulta o CNPJ 18.236.120/0001-58 e me diz quando foi fundado e qual o CNAE principal."
• "Quantas empresas brasileiras abriram em 2024 vs 2023? Quais estados mais cresceram?"
• "Acha toda empresa ativa onde 'Maria Silva' aparece como sócia, agrupando por estado."
• "Que outras empresas estão registradas no mesmo endereço da matriz do Magazine Luiza?"

A chave de API é obrigatória e gratuita: cria conta em cnpjaberto.com.br/planos, copia a chave e cola no campo env acima.

Quais ferramentas estão disponíveis

Cada tool exposta pelo MCP corresponde a uma rota da API REST, com parâmetros documentados e retorno estável. As nove disponíveis hoje:

A documentação completa está nos repositórios no GitHub (Python, Node/TS) e na página de demonstração.

E se eu não usar Claude?

Os dois pacotes também servem como SDKs puros, sem o servidor MCP no caminho. Cliente HTTP enxuto, exceções tipadas (NotFoundError, RateLimitError, AuthError), normalização de CNPJ com ou sem pontuação. Use o que combinar com sua stack.

Python:

from cnpjaberto import Client

with Client() as cnpj:                     # lê CNPJABERTO_API_KEY do ambiente
    empresa = cnpj.lookup("18.236.120/0001-58")
    print(empresa["razao_social"])

    snap = cnpj.panorama_year(2024)
    print(f"{snap['abertas']:,} abertas em 2024")

Node (TypeScript ou JavaScript):

import { Client } from "cnpjaberto";

const cnpj = new Client();                 // lê CNPJABERTO_API_KEY do ambiente

const empresa = await cnpj.lookup("18.236.120/0001-58");
console.log(empresa.razao_social);

const snap = await cnpj.panoramaYear(2024);
console.log(`${snap.abertas} abertas em 2024`);

A superfície dos dois pacotes é praticamente espelhada (apenas casing muda: snake_case no Python, camelCase no TS). É o mesmo cliente HTTP que o servidor MCP usa por baixo dos panos.

Roadmap

A v0.1 é deliberadamente minimalista. As próximas iterações têm coisas que valem mencionar:

• Cliente assíncrono (AsyncClient) no Python, para quem está em FastAPI, agentes async ou pipelines de scraping. (No Node, tudo já é Promise por padrão.)
• MCP hospedado em mcp.cnpjaberto.com.br via HTTP+SSE. Aí o usuário cola só uma URL no Claude, sem precisar instalar nada localmente.
• Endpoints Pro programáticos, como listar empresas de uma cidade inteira.

Para terminar

Se você é dev, integra via SDK ou MCP e nos diz o que faltou. Se você não é dev mas usa Claude todo dia, instala lá e brinca um pouco; em poucas perguntas dá pra perceber que ter dados estruturados em vez de "buscar no Google" muda a qualidade da conversa de uma forma difícil de voltar atrás.

O pacote é livre (licença MIT), o repositório é aberto e os PRs são bem-vindos.

• Python: pypi.org/project/cnpjaberto · github.com/cnpjaberto/cnpjaberto-py
• Node/TypeScript: npmjs.com/package/cnpjaberto · github.com/cnpjaberto/cnpjaberto-js
• Docs e demo: cnpjaberto.github.io/cnpjaberto-py

Se preferir começar pela API REST tradicional sem passar por SDK ou MCP, a página de desenvolvedores tem tudo: autenticação por X-API-Key, exemplos curl e plano gratuito de 1.000 requisições por dia.