Skip to content
Back to search

radar-cnpj-mcp

MCP server and CLI to find Brazilian companies by CNAE and region using Receita Federal open CNPJ data

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/wendersoon--radar-cnpj-mcp/badge.svg)](/listings/wendersoon--radar-cnpj-mcp)

HTML

<a href="/listings/wendersoon--radar-cnpj-mcp"><img src="/api/listings/wendersoon--radar-cnpj-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 219 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. # 📡 radar-cnpj-mcp
  3. **Encontre empresas por atividade e região na base pública de CNPJ da Receita Federal,
  4. direto do seu agente de IA ou do terminal.**
  5. [![CI](https://github.com/wendersoon/radar-cnpj-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/wendersoon/radar-cnpj-mcp/actions/workflows/ci.yml)
  6. [![MCP](https://img.shields.io/badge/MCP-server-8A2BE2)](https://modelcontextprotocol.io)
  7. [![Node](https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=white)](https://nodejs.org)
  8. [![Licença: MIT](https://img.shields.io/badge/licen%C3%A7a-MIT-blue)](LICENSE)
  9. ![Um agente de IA usando o radar-cnpj-mcp para consultar oficinas mecânicas em Campinas](assets/agente.gif)
  10. </div>
  11. ## Por que
  12. Você quer entender **quais empresas existem em um setor ou região**: quantas oficinas há em
  13. Campinas, quais academias abriram este ano em São Paulo, onde se concentram as clínicas
  14. odontológicas do estado.
  15. A Receita Federal publica o cadastro de **mais de 70 milhões de estabelecimentos**, mas em
  16. arquivos brutos de vários GB. O radar-cnpj-mcp transforma isso numa base local, consultada
  17. em milissegundos, que o seu agente de IA entende.
  18. - ⚡ **Instantâneo**: buscas em milissegundos, mesmo no Brasil inteiro
  19. - 🔒 **Local e gratuito**: os dados ficam na sua máquina, sem mensalidade nem limite de resultados
  20. - 🧠 **Feito para IA**: o agente traduz "oficina mecânica" para o CNAE certo e aplica os filtros
  21. - 🇧🇷 **Pensado para o Brasil**: busca sem acentos, MEI separado de microempresa, CSV pronto para o Excel
  22. ## Pergunte do seu jeito
  23. > **Você:** Quantas oficinas mecânicas ativas existem em Campinas?
  24. >
  25. > **Claude:** 2.301 estabelecimentos com a atividade principal 4520-0/01 (manutenção e
  26. > reparação mecânica de veículos). Desses, 1.407 são MEIs e 783 são microempresas.
  27. Outras ideias:
  28. - _"Liste academias abertas desde 2025 em Santo André, sem MEI, com telefone."_
  29. - _"Em quais cidades de SP há mais clínicas odontológicas?"_
  30. - _"Exporte para CSV os restaurantes do bairro Pinheiros."_
  31. - _"Como é a economia de Campinas?"_
  32. - _"Onde há mais clínicas odontológicas: Campinas, Santos ou Sorocaba?"_
  33. - _"As aberturas de academias em SP estão crescendo?"_
  34. ## Como usar
  35. Requer [Node.js](https://nodejs.org) 20 ou superior.
  36. **1. Baixe os dados da Receita Federal.** O comando busca os arquivos do mês mais recente direto
  37. da Receita e monta a base na sua máquina, só com as UFs pedidas. O projeto não hospeda nem
  38. redistribui os dados.
  39. ```sh
  40. npx -y radar-cnpj-mcp baixar --ufs SP,MG
  41. ```
  42. São cerca de 7 GB de download, mesmo para uma só UF, porque a Receita não separa os arquivos por
  43. estado. Reserve cerca de 20 GB livres durante o processo; ao final, os arquivos temporários são
  44. apagados e fica só a base (1,9 GB para SP e AC). Com SP e AC, levou cerca de 33 minutos, dos quais
  45. 18 de download; o tempo depende da sua conexão e da máquina. Para guardar os ZIPs, use
  46. `--manter-arquivos <pasta>`. Para o Brasil inteiro, troque `--ufs` por `--todas`, o que exige mais
  47. tempo e espaço.
  48. <details>
  49. <summary><b>Prefere baixar pelo navegador?</b></summary>
  50. 1. Abra a [pasta do CNPJ na Receita Federal](https://arquivos.receitafederal.gov.br/index.php/s/gn672Ad4CF8N6TK?dir=/Dados/Cadastros/CNPJ)
  51. e entre na pasta do mês mais recente (por exemplo, `2026-10`).
  52. 2. Baixe, para uma mesma pasta, os arquivos `Estabelecimentos*.zip`, `Empresas*.zip`,
  53. `Simples.zip`, `Cnaes.zip` e `Municipios.zip`. Não é preciso descompactar. Os demais, como
  54. `Socios*.zip`, não são usados.
  55. 3. Importe a pasta:
  56. ```sh
  57. npx -y radar-cnpj-mcp importar ~/Downloads/2026-10 --ufs SP,MG
  58. ```
  59. </details>
  60. **2. Conecte ao seu agente de IA.**
  61. <details open>
  62. <summary><b>Claude Code</b></summary>
  63. ```sh
  64. claude mcp add radar-cnpj -- npx -y radar-cnpj-mcp
  65. ```
  66. </details>
  67. <details>
  68. <summary><b>Claude Desktop, Cursor, VS Code e outros</b></summary>
  69. ```json
  70. {
  71. "mcpServers": {
  72. "radar-cnpj": {
  73. "command": "npx",
  74. "args": ["-y", "radar-cnpj-mcp"]
  75. }
  76. }
  77. }
  78. ```
  79. </details>
  80. Pronto: peça ao agente o que procura. Para atualizar a base todo mês, rode o `baixar` de novo.
  81. Também dá para pedir ao agente: _"Baixe os dados da Receita para SP e MG."_ Ele confirma com você
  82. e o download continua em segundo plano, mesmo se você fechar o agente. Cada download substitui a
  83. base atual, então inclua todas as UFs que quiser manter.
  84. ### Instalação via npm
  85. Se preferir instalar em vez de usar o `npx`:
  86. ```sh
  87. npm install -g radar-cnpj-mcp
  88. radar-cnpj-mcp baixar --ufs SP,MG
  89. ```
  90. E configure o agente com o comando instalado:
  91. ```sh
  92. claude mcp add radar-cnpj -- radar-cnpj-mcp
  93. ```
  94. ```json
  95. {
  96. "mcpServers": {
  97. "radar-cnpj": { "command": "radar-cnpj-mcp" }
  98. }
  99. }
  100. ```
  101. Para atualizar a ferramenta: `npm update -g radar-cnpj-mcp`.
  102. ## O que o agente ganha
  103. | Ferramenta | O que faz |
  104. | -------------------- | ---------------------------------------------------------------------------- |
  105. | `buscar_empresas` | Lista empresas com CNPJ, razão social, atividade, endereço e contatos |
  106. | `contar_empresas` | Conta empresas, agrupando por UF, município, bairro, CNAE, porte, MEI ou ano |
  107. | `buscar_cnae` | Descobre o código CNAE a partir da descrição da atividade |
  108. | `buscar_municipio` | Encontra municípios pelo nome |
  109. | `detalhar_empresa` | Mostra todos os dados de um CNPJ |
  110. | `exportar_csv` | Gera uma planilha CSV pronta para o Excel |
  111. | `status_base` | Informa o mês de referência e as UFs importadas |
  112. | `perfil_municipio` | Resume a economia de um município: setores, porte, MEIs e aberturas recentes |
  113. | `comparar_regioes` | Compara até 5 municípios ou UFs, no mesmo setor ou em todos |
  114. | `tendencia_setor` | Mostra aberturas e baixas por ano ou mês, a partir da base atual |
  115. | `baixar_dados` | Baixa os dados da Receita em segundo plano, a pedido do usuário |
  116. | `andamento_download` | Mostra a etapa do download iniciado pelo agente |
  117. **Filtros:** CNAE (exato ou por prefixo, principal ou secundário), UF, município, bairro,
  118. CEP, situação cadastral, data de abertura, porte, MEI, matriz/filial, capital social e
  119. existência de telefone ou e-mail.
  120. **Atalhos (prompts):** `consultar_empresas`, `panorama_setor` e `empresas_recentes`. No Claude
  121. Code, viram comandos como `/radar-cnpj:consultar_empresas`.
  122. **Resources:** `radar://status`, `radar://cnaes`, `radar://municipios/{uf}` e
  123. `radar://empresa/{cnpj}`, para anexar à conversa.
  124. ## No terminal
  125. ![Contagem de empresas e oficinas mecânicas em São Paulo pelo terminal](assets/terminal.gif)
  126. ```sh
  127. npx radar-cnpj-mcp contar --cnae 4520-0/01 --uf SP --agrupar municipio
  128. npx radar-cnpj-mcp buscar --cnae 4520-0/01 --municipio Campinas --sem-mei --limite 20
  129. npx radar-cnpj-mcp buscar --cnae 4520 --municipio Campinas --csv oficinas.csv
  130. npx radar-cnpj-mcp status
  131. npx radar-cnpj-mcp --help
  132. ```
  133. ## Privacidade
  134. Os dados vêm direto da Receita Federal e ficam na sua máquina. Se o seu agente de IA roda na
  135. nuvem, os resultados das consultas são enviados ao provedor dele. Telefone e e-mail de MEIs
  136. costumam ser os da própria pessoa física: para ocultá-los, peça ao agente ou use
  137. `--ocultar-contatos-mei` no terminal. Ao usar os dados para contatar empresas, respeite a LGPD:
  138. faça ofertas ligadas à atividade delas e ofereça uma forma de não serem mais contatadas.
  139. ## Desenvolvimento
  140. ```sh
  141. npm install
  142. npm test # testes
  143. npm run lint # Biome
  144. npm run typecheck
  145. npm run build
  146. ```
  147. ## Contribuindo
  148. Contribuições são bem-vindas! Veja o [CONTRIBUTING.md](CONTRIBUTING.md).
  149. ## Licença
  150. [MIT](LICENSE). Dados: [Receita Federal do Brasil – Dados Abertos do
  151. CNPJ](https://arquivos.receitafederal.gov.br/).
  152. ## LGPD
  153. O radar-cnpj-mcp é uma ferramenta de código aberto. O projeto não hospeda nem coleta dados: cada
  154. pessoa baixa a base pública de CNPJ direto da Receita Federal e consulta na própria máquina.
  155. Por isso, não temos dados para excluir ou filtrar. Pedidos de alteração ou remoção devem ser feitos
  156. à Receita Federal.
  157. Quem usa a ferramenta responde pelo próprio uso dos dados, inclusive perante a LGPD.
  158. Os dados de sócios não são importados. A razão social de MEIs e empresários individuais pode conter
  159. o nome da pessoa, e os contatos de MEIs costumam ser os dela, como constam na base da Receita. Este
  160. aviso não é um parecer jurídico.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.