# cnpj-mcp

Servidor MCP de CNPJ **sem base local, sem conta e sem serviço pago**.

| Ferramenta | Fonte |
|---|---|
| `consultar_cnpj` | API Minha Receita (reservas: OpenCNPJ, CNPJá Open) |
| `buscar_empresas_por_filtro` | API Minha Receita (UF, CNAE, município, natureza jurídica) |
| `processos_djen` | API pública do Diário de Justiça Eletrônico Nacional (CNJ) |
| `buscar_socio`, `empresas_do_socio` | arquivos Parquet publicados (ver abaixo) |
| `buscar_empresa_por_nome` | arquivos Parquet |
| `empresas_no_endereco` | arquivos Parquet |
| `socios_em_comum`, `rede_societaria` | arquivos Parquet |
| `info_base` | `meta.json` dos arquivos |

## Como funciona a parte "sem base local"

`gerar-dados.mjs` baixa os dados abertos de CNPJ da Receita Federal e gera cinco arquivos Parquet,
cada um **ordenado pela coluna de busca** (nome do sócio, CNPJ, documento do sócio, razão social, CEP).
Os arquivos ficam publicados na internet (Hugging Face). O MCP consulta com DuckDB por requisições
parciais: numa busca por nome exato, lê cerca de 1 MB de um arquivo de centenas de MB.

Os modos `contem` (trecho no meio do nome) usam índices só de nomes (`pessoas`, `nomes_empresas`)
com blocos grandes, para gastar poucos pedidos: o Hugging Face limita cada IP a 3.000 pedidos a cada
5 minutos.

Tempos medidos pela internet em 16/10/2026, numa mesma sessão (o primeiro uso de cada arquivo baixa
o índice dele, de 5 a 7 s):

| Consulta | Tempo |
|---|---|
| Sócio pelo nome exato, empresas do sócio, sócios em comum | 1 a 6 s |
| Rede societária, 2 níveis (~90 nós) | ~10 s |
| Rede societária, 3 níveis (~165 nós) | ~15 s |
| Sócio por trecho do nome | ~10 s na primeira vez, ~3 s depois |
| Empresa por trecho do nome | ~30 s |
| Ficha do CNPJ, DJEN | menos de 1 s |

Telefone e e-mail **não** entram nos arquivos (minimização de dado pessoal); estão na ficha do CNPJ.

## Usar

```
git clone https://github.com/leorochasf/cnpj-mcp && cd cnpj-mcp && npm install
claude mcp add cnpj --scope user -- node /caminho/para/cnpj-mcp/index.js
```

Por padrão o MCP lê os arquivos publicados no Hugging Face (`CNPJ_DADOS` muda a origem).

`CNPJ_DADOS` também aceita uma pasta local com os `.parquet` (por exemplo `saida/2026-10`).

## Atualização mensal

`.github/workflows/atualizar-dados.yml` roda todo dia 20: se a Receita publicou um mês novo, gera
os arquivos e envia ao Hugging Face. Configure no repositório do GitHub o secret `HF_TOKEN`
(token de escrita) e a variável `HF_DATASET` (ex.: `usuario/cnpj-receita`).

Para gerar à mão: `node gerar-dados.mjs [AAAA-MM]` → `saida/AAAA-MM/`.

## Limites que importam

- O CPF de sócio vem **mascarado** pela Receita (`***123456**`). Nome + esse trecho separa homônimos
  quase sempre, mas não com certeza absoluta.
- O DJEN é buscado pelo **nome** da parte: homônimos aparecem. A API aceita cerca de 20 consultas por
  minuto.
- As APIs públicas são mantidas por terceiros e podem ficar lentas ou fora do ar.
- `municipios-ibge.json` é a lista de municípios do IBGE salva em 15/10/2026.

## Dados pessoais

Os arquivos trazem nomes de sócios publicados pela Receita Federal. São dados públicos, mas a LGPD
continua aplicável. Lei 13.709/2018, art. 7º, § 3º: "O tratamento de dados pessoais cujo acesso é
público deve considerar a finalidade, a boa-fé e o interesse público que justificaram sua
disponibilização." Não tente reidentificar CPFs.

## Licença

Código sob a GNU Affero General Public License v3.0 (`LICENSE`). Os dados são da Receita Federal.