cnpjaberto

SDK Python e servidor Model Context Protocol (MCP) para o CNPJ Aberto. A versão 0.2.0 oferece 44 ferramentas: consulta cadastral, busca avançada, prospecção, vínculos societários, recursos PRO, compliance, panoramas publicados e catálogos B3/CVM.

Python 3.10+. O SDK é síncrono; o servidor MCP executa as consultas em workers para não bloquear o protocolo.

pip install cnpjaberto
pip install 'cnpjaberto[mcp]'
export CNPJABERTO_API_KEY=sua_chave_aqui

Crie sua chave na conta do CNPJ Aberto. Todas as consultas de integração usam X-API-Key e consomem a cota da conta. O servidor determina acesso, cotas e vigência do plano; o SDK não fixa valores de cota nem presume que uma chave tenha PRO.

SDK

from cnpjaberto import Client

with Client() as cnpj:
    empresa = cnpj.lookup("18.236.120/0001-58")
    print(empresa["razao_social"])
    # Com API key, contém apenas o estabelecimento solicitado.
    print(empresa["estabelecimentos"])

    filiais = cnpj.filiais("18236120000158", uf="SP", q="centro", per_page=200)
    busca = cnpj.search("nubank", per_page=5)
    cidades = cnpj.search_municipalities("São Paulo", uf="SP")
    empresas = cnpj.advanced_search(
        uf="SP", municipio_codigo="7107", cnae="6201501", mei=False,
    )
    panorama = cnpj.panorama_year(2025, sem_mei=True)

PRO usa a mesma chave da conta, sem um modo especial:

from cnpjaberto import Client, ProRequiredError

with Client() as cnpj:
    try:
        dossie = cnpj.compliance_dossier("18236120000158")
        grupo = cnpj.business_group("18236120000158")
        cruzamento = cnpj.common_owners(["18236120", "00000000"])
        leads = cnpj.leads("SP", "7107", com_email=True)
    except ProRequiredError as error:
        print(error.payload)  # detalhe do backend, incluindo upgrade_url quando presente

Os nomes dos parâmetros novos acompanham a API (nome, municipio_codigo, sem_mei, etc.). Os parâmetros legados continuam disponíveis, como companies_by_owner(name=...) e search(q=...). Métodos retornam o JSON original, incluindo indicadores de prévia/bloqueio. search_cnaes, search_municipalities e municipalities retornam listas; panorama_csv retorna texto CSV.

Client(api_key=..., base_url=..., timeout=30) permite configuração explícita. Um httpx.Client injetado com client=... pertence ao chamador e não será fechado pelo SDK; o transporte mantém sua configuração de timeout. O SDK aplica sua base URL e chave mesmo ao transporte injetado. Clientes criados pelo SDK são fechados no with ou em close().

Related MCP server: brdata-mcp

Servidor MCP

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

Use o caminho absoluto do executável se o aplicativo não o encontrar no PATH. Também é possível executar python -m cnpjaberto.mcp. O transporte é stdio; stdout fica reservado ao JSON-RPC. CNPJABERTO_BASE_URL substitui a URL padrão no servidor MCP. Credenciais são configuração do processo, nunca argumentos das ferramentas.

O recurso cnpjaberto://guide descreve autenticação, planos, cotas e interpretação dos dados. Todas as ferramentas consultam dados, inclusive o POST de resumos em lote, e têm anotações MCP de leitura. Cada chamada pode consumir cota. Não há repetição automática de chamadas HTTP. O cliente compartilhado é fechado no encerramento, inclusive quando a sessão é cancelada.

O extra MCP mantém a linha compatível mcp>=1.28,<2, conforme a orientação oficial para v1. O SDK HTTP continua utilizável sem esse extra.

Ferramentas e métodos

Os nomes MCP coincidem com os métodos do SDK, exceto lookup_cnpj → lookup, list_filiais → filiais e search_companies(query=...) → search(q=...).

Planos e limites de integração

• PRO: endereço/contato compartilhado, participações, grupo empresarial, árvore de controle, sócios em comum, empresas por cidade e dossiê de compliance. O backend também reconhece planos Starter ativos conforme suas regras de vigência.

• Busca avançada: filtros usuais disponíveis no Free; presença ou valor de e-mail/telefone e endereço exato exigem PRO.

• Leads: UF e código de município são obrigatórios. Free recebe contatos mascarados e contact_gated; PRO recebe contatos disponíveis na base. Não use os valores mascarados como dados reais.

• Raio-X: Free recebe prévia; PRO recebe a análise completa. O SDK preserva a resposta e seus indicadores de bloqueio.

• Limites: busca textual exige 4 caracteres, páginas 1–50 e até 20 resultados. Filiais aceitam páginas/tamanho até 200 e busca q. Busca avançada/leads aceitam até 50 páginas de 50 resultados. Busca de sócios: 25 páginas de 50. Empresas por cidade: 200 páginas de 100. Resumos em lote: até 10.000 itens, com resultados na mesma ordem.

• Sessão web: /api/exports e /api/auth/api-key/* ainda exigem autenticação de sessão, e não funcionam só com X-API-Key. Não são expostos como ferramentas de integração. Exportações privadas, rotação de chave, cobrança, administração e chat interno não fazem parte deste SDK. panorama_csv é a exportação de uma publicação pública e está disponível.

Erros

from cnpjaberto import Client, AuthError, ProRequiredError, RateLimitError

with Client() as cnpj:
    try:
        cnpj.companies_by_contact(email="contato@example.com")
    except ProRequiredError as error:  # 403; subclasse de AuthError
        print("Acesso negado:", error.payload)
    except AuthError as error:        # 401
        print("Verifique a chave:", error.payload)
    except RateLimitError as error:   # 429: throttle ou cota diária/mensal
        print("Aguarde:", error.retry_after, error.payload)

CnpjAbertoError é a base; NotFoundError representa 404 e QuotaExceededError representa 402. Todos preservam status_code, payload, headers e retry_after quando disponíveis. Outros erros HTTP, JSON inválido e falhas de transporte usam a classe base. Redirecionamentos não são seguidos. Validações locais lançam ValueError; validações adicionais do backend preservam o erro 400/422. O MCP reporta falhas como erros de ferramenta, com detalhes da API e Retry-After quando presente, em vez de resultados vazios.

Migração da versão 0.1

Os nove nomes MCP originais foram preservados. Mudanças de contrato necessárias:

• CNPJ completo tem 14 caracteres, aceita letras ASCII em maiúsculas/minúsculas nas primeiras 12 posições e mantém os dois verificadores numéricos. Máscaras são removidas sem descartar letras. Lookup e filiais não aceitam os prefixos de 8/12 caracteres anunciados pela versão antiga. A validação do dígito verificador fica com a API.

• lookup com chave retorna apenas o estabelecimento solicitado. Consulte filiais para os demais.

• Busca textual passou de 3 para 4 caracteres.

• Joins por endereço e contato exigem PRO na integração. companies_by_contact agora também expõe exclude no MCP.

• filiais ganhou q; panoramas nacional/anual ganharam sem_mei.

• close() não fecha um transporte HTTP fornecido pelo chamador.

Desenvolvimento e validação

python -m venv .venv
.venv/bin/python -m pip install -e '.[mcp,dev]' hatchling
.venv/bin/ruff check src tests examples
.venv/bin/ruff format --check src tests examples
.venv/bin/pytest
.venv/bin/python -m build --no-isolation

Contratos revisados contra o backend do repositório cnpj, commit 50b17005c81d4c81f2faebd8f322dc5e93d66405 (2026-10-04), incluindo rotas, serviços de autenticação e gates de plano. Testes usam transporte HTTP simulado e sessões MCP reais em memória/stdio; não requerem conta e não consomem cota. Cobrem todas as ferramentas, serialização, erros, planos, schemas e encerramento. Não substituem uma consulta autenticada de ponta a ponta ao ambiente de produção.

Fontes de dados

Cadastro empresarial da Receita Federal, complementado pelos conjuntos disponibilizados pelo backend para compliance, dívida ativa, B3/CVM e publicações do panorama. Consulte os metadados da resposta para cobertura e atualização; indicadores não constituem prova de irregularidade.

Licença

MIT.