cnpjaberto
SDK em Python e servidor Model Context Protocol (MCP) para o cnpjaberto.com.br, o cadastro aberto de empresas brasileiras (CNPJ). Permite consulta de empresa, grafo de sócios, joins por endereço e contato, estatísticas por CNAE, e panoramas nacional e anual.
pip install cnpjaberto # apenas SDK
pip install cnpjaberto[mcp] # SDK + servidor MCP para Claude Desktop e similares
Início rápido com o SDK
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"])
achados = cnpj.search("nubank", per_page=5)
for h in achados["results"]:
print(h["cnpj"], h["razao_social"])
snap = cnpj.panorama_year(2024)
print(f"{snap['abertas']:,} abertas, {snap['fechadas']:,} fechadas em 2024")
A chave de API é obrigatória. Crie uma conta gratuita em cnpjaberto.com.br/planos, copie sua chave e exporte:
export CNPJABERTO_API_KEY=sua_chave_aqui
Servidor MCP (Claude Desktop, Cursor, Cline)
Instale o extra e adicione esta config no seu cliente.
pip install cnpjaberto[mcp]
~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"cnpjaberto": {
"command": "cnpjaberto-mcp",
"env": { "CNPJABERTO_API_KEY": "sua_chave_aqui" }
}
}
}
Reinicie o Claude Desktop. Agora dá para perguntar coisas como:
- "Consulta o CNPJ 18.236.120/0001-58 e me diz quando foi fundado."
- "Quantas empresas brasileiras abriram em 2024 vs 2023? Quais estados mais cresceram?"
- "Acha empresas onde 'Maria Silva' aparece como sócia, agrupando por estado."
- "Que outras empresas estão registradas no mesmo endereço da matriz da Magazine Luiza?"
Tools expostas
| Tool | O que retorna |
|---|---|
lookup_cnpj(cnpj) | Registro completo: razão social, capital, sócios, com estabelecimentos[] (matriz e filiais, endereço, telefones, CNAEs) |
list_filiais(cnpj) | Filiais de uma matriz, paginado, filtro opcional por UF |
search_companies(query) | Busca por razão social, fantasia ou dígitos do CNPJ (mínimo 3 chars) |
companies_by_owner(name) | Empresas onde a pessoa aparece como sócia; cpf ajuda a desambiguar homônimos |
companies_at_same_address(cep, logradouro, numero) | Outras empresas registradas no mesmo endereço |
companies_by_contact(email | ddd+telefone) | Empresas que compartilham o mesmo email ou telefone |
cnae_stats(codigo) | Estatísticas agregadas de um CNAE (contagem, top UFs, top municípios) |
panorama_overview() | Estatísticas nacionais: top UFs e CNAEs, faixas de capital, idade, histórico de 10 anos |
panorama_year(year) | Recorte anual: aberturas e fechamentos, série mensal, fatia MEI |
Erros tipados
from cnpjaberto import Client, NotFoundError, RateLimitError, AuthError
with Client() as cnpj:
try:
cnpj.lookup("00000000000000")
except NotFoundError:
...
except RateLimitError as e:
print("Cota diária:", e.payload)
except AuthError:
...
Fonte de dados
Todos os dados vêm do dump público de CNPJ da Receita Federal, atualizado mensalmente. O cnpjaberto.com.br ingere, indexa e serve com lookups sub-segundo, mais joins de valor agregado (grafo de sócios, endereços compartilhados, agregados por CNAE) sobre cerca de 70 milhões de estabelecimentos e 67 milhões de empresas.
Licença
MIT.