# mcp-empresas-brasil

**Servidor MCP do cadastro de empresas do Brasil (Receita Federal, dados abertos do CNPJ) — com as armadilhas do dump oficial declaradas na resposta.**

Quatro tools que não mentem, em vez de quarenta que não sabem.

---

## O problema que este servidor resolve

O dump mensal do CNPJ é a melhor fotografia pública das empresas do país — e é fácil tirar
dele um número errado sem perceber:

> **O código de município da Receita não é o do IBGE.** Canoas/RS é `8589` no dump e `4304606`
> no IBGE. E a tabela de municípios da Receita **nem traz a UF** — só código e nome sem acento.
> Qualquer cruzamento direto com IBGE, DATASUS ou CNES volta **vazio, sem erro**.

E não é o único: contar só pelo **CNAE principal** subestima o setor (muita empresa registra a
atividade de interesse como secundária); **"ATIVA" não é "operando"**; e **cada filial é um
estabelecimento**, então uma rede de 20 lojas vira 20.

Este servidor guarda só o **recorte de CNAEs** que você pede, **converte o município para IBGE**
no build (e lista o que não casou), e devolve cada contagem com os caveats que se aplicam.

## A garantia

Toda resposta segue o **phi-data-contract v0.1**: `data` + `provenance` (mês do dump, recorte,
data de construção) + `caveats` (com evidência e data de verificação) + `cannot_answer` (o que a
pergunta pediu e o cadastro não responde — por exemplo, número de profissionais ou faturamento).

## Privacidade

Guardados: CNPJ, nome fantasia, atividade, situação, data de abertura, bairro, CEP, município,
porte, capital social, natureza jurídica e **razão social apenas de pessoa jurídica**. A razão social
**não** é guardada quando a natureza é de pessoa física — empresário individual/MEI (213-5), EIRELI
(230-5, 231-3), sociedade unipessoal de advocacia (232-1) e naturezas 4xxx —, porque ali ela é o nome
de uma pessoa. **E-mail, telefone e sócios nunca são lidos.**

## Instalação

Requer **Node ≥ 22.5**.

```bash
npm install && npm run build
npm run db:build -- --preset odontologia                    # último mês publicado (~4 GB baixados, ~20 min)
npm run db:build -- --cnaes 4645103,8630504 --mes 2026-09   # recorte próprio
npm run db:build -- --preset odontologia --partes 1         # teste rápido: 1 de 10 arquivos
```

Cada zip é baixado para um temporário, lido em stream e apagado. **Nada é redistribuído.**

```json
{ "mcpServers": { "empresas": { "command": "node", "args": ["--experimental-sqlite", "/caminho/mcp-empresas-brasil/dist/index.js"] } } }
```

## As tools

| Tool | O que faz |
|---|---|
| `empresas_contagem` | Estabelecimentos (ou empresas = CNPJ básico) por município IBGE, UF, CNAE, grupo, porte ou situação. Diz quantos entraram pelo CNAE principal. |
| `empresas_listar` | Estabelecimentos de um município ou UF no recorte, ordenados por capital social. |
| `empresas_cnpj` | Um estabelecimento do recorte pelo CNPJ. |
| `empresas_data_caveats` | As armadilhas + o relatório do build (mês, recorte, municípios que não casaram). |

O preset **`odontologia`** cobre a cadeia dental: atacado odontológico e médico-hospitalar,
máquinas odonto-médicas, representantes comerciais odonto-médico-hospitalares, varejo de artigos médicos, atividade odontológica, prótese dentária e
fabricação de materiais — agrupados em `distribuicao`, `representacao`, `varejo`, `clinica`, `laboratorio`, `industria`.

## Os caveats

| id | Severidade | Corrigido? |
|---|---|---|
| `municipio_receita_nao_e_ibge` | crítico | ✅ convertido no build (nome + UF), não casados listados |
| `cnae_secundario_subconta` | crítico | ✅ padrão "principal ou secundário", com a origem de cada linha |
| `pessoa_fisica_fora_do_cnpj` | crítico | ❌ impossível — o dado não está no CNPJ; declarado em `cannot_answer` |
| `ativa_nao_e_operando` | aviso | ❌ exige outra fonte |
| `estabelecimento_nao_e_empresa` | aviso | ✅ `contar: "empresas"` |
| `recorte_fixo_no_build` | info | — |

```bash
npm test
```

Fonte: Receita Federal do Brasil — Dados Abertos do CNPJ (compartilhamento público em
`arquivos.receitafederal.gov.br`, acesso WebDAV). Conversão de município: IBGE Localidades.

MIT · Autor: **Luis Delfin** · parte da rede de servidores MCP de dados públicos de [Phi AI](https://phiai.io)

---

# English

**MCP server for Brazil's company registry (Federal Revenue open CNPJ data) — with the official dump's traps declared in the response.**

The Revenue municipality code is **not** the IBGE code (Canoas/RS = `8589` in the dump, `4304606`
at IBGE), and the Revenue municipality table has no state. Direct joins with IBGE, DATASUS or CNES
return **empty, silently**. Counting by main activity code only undercounts; "active" is not
"operating"; each branch is a separate establishment.

This server keeps only the CNAE cut you request, converts municipalities to IBGE at build time
(listing what didn't match), and returns every count with the caveats that apply —
**phi-data-contract v0.1**. Company name is stored only for legal entities (never for sole traders /
micro-entrepreneurs, where it is a person's name); e-mail, phone and partners are never read.

Requires Node ≥ 22.5 · `npm run db:build -- --preset odontologia` · no data is redistributed.

MIT · Author: **Luis Delfin**