Skip to content
Back to search

mcp-fiscal-brasil

Servidor MCP fiscal brasileiro: CNPJ, NF-e, NFS-e, CT-e, SPED, eSocial, Simples Nacional, Reforma 2026. 44 tools, zero-cadastro, tabelas offline. Python.

Safety scan

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

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/DeHor-Labs/mcp-fiscal-brasil with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/DeHor-Labs/mcp-fiscal-brasil'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dehor-labs--mcp-fiscal-brasil/badge.svg)](/listings/dehor-labs--mcp-fiscal-brasil)

HTML

<a href="/listings/dehor-labs--mcp-fiscal-brasil"><img src="/api/listings/dehor-labs--mcp-fiscal-brasil/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 · 683 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. <!-- mcp-name: io.github.DeHor-Labs/mcp-fiscal-brasil -->
  2. <p align="center">
  3. <img src="https://raw.githubusercontent.com/DeHor-Labs/mcp-fiscal-brasil/main/assets/banner.svg" width="800" alt="MCP Fiscal Brasil">
  4. </p>
  5. <p align="center">
  6. <strong>O único servidor MCP com suporte nativo a NF-e, NFS-e, SPED, eSocial, Simples Nacional e Reforma Tributária 2026 (IBS/CBS) - sem conta, sem chave e sem configuração.</strong>
  7. </p>
  8. <p align="center">
  9. <a href="https://pypi.org/project/mcp-fiscal-brasil/"><img src="https://img.shields.io/pypi/v/mcp-fiscal-brasil?color=009c3b&label=PyPI" alt="PyPI version"></a>
  10. <a href="https://pypi.org/project/mcp-fiscal-brasil/"><img src="https://img.shields.io/pypi/dm/mcp-fiscal-brasil?color=009c3b&label=downloads%2Fm%C3%AAs" alt="PyPI downloads"></a>
  11. <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11%2B-002776?logo=python&logoColor=white" alt="Python 3.11+"></a>
  12. <a href="https://github.com/DeHor-Labs/mcp-fiscal-brasil/actions/workflows/ci.yml"><img src="https://github.com/DeHor-Labs/mcp-fiscal-brasil/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  13. <img src="https://img.shields.io/badge/cobertura-85%25-009c3b?labelColor=002776" alt="Cobertura de testes 85%">
  14. <a href="LICENSE"><img src="https://img.shields.io/badge/licenca-MIT-FFDF00?labelColor=002776" alt="License MIT"></a>
  15. <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatível-7c3aed" alt="MCP Compatible"></a>
  16. <img src="https://img.shields.io/github/stars/DeHor-Labs/mcp-fiscal-brasil?style=flat&color=009c3b" alt="Stars">
  17. <img src="https://img.shields.io/github/issues/DeHor-Labs/mcp-fiscal-brasil?color=FFDF00&labelColor=002776" alt="Issues">
  18. </p>
  19. <p align="center">
  20. <a href="https://fiscal.dehor.dev">🌐 Site</a> ·
  21. <a href="https://dehor-labs.github.io/mcp-fiscal-brasil/">📚 Documentação</a> ·
  22. <a href="#-instalação">Instalação</a> ·
  23. <a href="#-ferramentas-disponíveis">Ferramentas</a> ·
  24. <a href="#workflows-que-vendem-sozinho">Workflows</a> ·
  25. <a href="#-roadmap">Roadmap</a> ·
  26. <a href="#-contribuindo">Contribuindo</a>
  27. </p>
  28. ---
  29. ## Início rápido
  30. ```bash
  31. uvx mcp-fiscal-brasil
  32. ```
  33. > **Para manter sempre atualizado:** `uvx` cacheia a versão instalada. Use `uvx mcp-fiscal-brasil@latest` ou `uvx --refresh mcp-fiscal-brasil` para forçar a versão mais recente do [PyPI](https://pypi.org/project/mcp-fiscal-brasil/).
  34. ### Claude Desktop
  35. Edite `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) ou `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
  36. ```json
  37. {
  38. "mcpServers": {
  39. "fiscal-brasil": {
  40. "command": "uvx",
  41. "args": ["mcp-fiscal-brasil"]
  42. }
  43. }
  44. }
  45. ```
  46. Reinicie o Claude Desktop. As ferramentas fiscais aparecem automaticamente, sem nenhuma chave de API.
  47. ---
  48. ## Por que mcp-fiscal-brasil e não outros servidores MCP brasileiros?
  49. | Funcionalidade | mcp-fiscal-brasil | mcp-brasil | brasil-data-mcp |
  50. |---|:---:|:---:|:---:|
  51. | Foco | Vertical fiscal profunda | Dados públicos gerais | Dados públicos gerais |
  52. | NF-e: parse, validação, DANFE, assinatura | Sim | Não | Não |
  53. | SPED/eSocial: análise offline | Sim | Não | Não |
  54. | Tabelas offline (NCM, CFOP, CNAE) | Sim | Não | Não |
  55. | Reforma Tributária 2026 (IBS/CBS) | Sim | Não | Não |
  56. | Simples Nacional/MEI | Sim | Não | Não |
  57. | Certidão federal/FGTS | Sim (orientação) | Não | Não |
  58. | Certificado A1 (mTLS SEFAZ) | Sim (opt-in) | Não | Não |
  59. | Zero-cadastro, zero chave obrigatória | Sim | Parcial (3 APIs exigem chave) | Sim |
  60. | Tools agênticas de alto nível | Sim (6 tools) | Parcial | Não |
  61. | Linguagem de implementação | Python | Python | Node.js |
  62. **mcp-brasil** (1.6k stars) e **brasil-data-mcp** cobrem dados públicos gerais - CEP, bancos, feriados, economia. Este projeto faz algo diferente: é uma vertical fiscal, com parsing offline de XML, validação XSD, tabelas de referência embutidas e suporte à Reforma 2026. Focos diferentes, públicos distintos.
  63. ---
  64. ## O que é
  65. `mcp-fiscal-brasil` conecta assistentes de IA, ERPs, CRMs e automações internas ao universo fiscal brasileiro: **CNPJ, CPF, Simples Nacional, NFe, NFSe, SPED, eSocial, certidões e due diligence de fornecedores**.
  66. Ele não tenta ser um catálogo genérico de dados públicos. A proposta é ser uma vertical de produto: transformar consultas fiscais fragmentadas em **tools seguras, composáveis e prontas para agentes**.
  67. ### Workflows que vendem sozinho
  68. | Workflow | Tool principal | Resultado |
  69. |----------|----------------|-----------|
  70. | Due diligence de fornecedor | `risk_score_supplier` | Score 0-100, risco, fatores e recomendação de contratação |
  71. | Triagem em lote | `consultar_empresas_lote` | Vários CNPJs em uma chamada, com compliance + score por empresa |
  72. | Compliance de CNPJ | `analyze_cnpj_compliance` | CNPJ + Simples/MEI + CNAE em relatório acionável |
  73. | Validação de NFe | `validate_nfe_full` | XML + chave + emissor, com issues estruturadas |
  74. | Sumário de SPED | `summarize_sped` | Resumo executivo, período, empresa, blocos e inconsistências |
  75. | Planejamento tributário | `compare_tax_regimes` | Comparativo MEI, Simples, Lucro Presumido e Lucro Real |
  76. ---
  77. ## 🌎 Demo ao vivo
  78. Web UI demo hospedada (Render free tier, pode demorar 30s no primeiro acesso pra acordar):
  79. [![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/DeHor-Labs/mcp-fiscal-brasil)
  80. Você pode clicar no botão acima pra hostear sua própria instância em 3 cliques no Render.com.
  81. Veja [docs/getting-started/deploy.md](docs/getting-started/deploy.md) para outras opções (Fly.io, auto-host via Docker).
  82. ---
  83. ## ✨ Novidades v0.2.x
  84. Versão de evolução com 4 frentes:
  85. - **8 novas fontes de dados**: CNAE, CPF, Simples Nacional, MEI, IBGE, CEP, Empresa consolidada, Certidões
  86. - **Tools agênticas** (alto nível): `analyze_cnpj_compliance`, `risk_score_supplier`, `consultar_empresas_lote`, `compare_tax_regimes`, `validate_nfe_full`, `summarize_sped`
  87. - **Múltiplas interfaces**: além do servidor MCP, agora CLI (`mcp-fiscal`), REST API (`mcp-fiscal-api`) com Web UI demo, e wrapper Node.js em preview (`npm-wrapper/`)
  88. - **Production-grade**: HTTP client com retry exponencial, cache pluggável, rate-limit por host, logs JSON estruturados
  89. ```bash
  90. # CLI standalone
  91. mcp-fiscal cnpj 12345678000190
  92. mcp-fiscal compliance 12345678000190
  93. mcp-fiscal regimes --faturamento 500000 --setor serviços --folha 180000
  94. # REST API + Web UI demo
  95. mcp-fiscal-api # http://localhost:8000
  96. # Node.js
  97. import { analyzeCompliance } from "mcp-fiscal-brasil";
  98. ```
  99. Veja [CHANGELOG.md](CHANGELOG.md) para detalhes.
  100. ---
  101. ## Por que este projeto existe?
  102. O Brasil tem uma das infraestruturas fiscais mais complexas do mundo. São **27 SEFAZs** estaduais, **NFe + NFSe + SPED + eSocial**, milhares de municípios com portais próprios e milhões de empresas tentando manter conformidade fiscal todos os dias.
  103. Antes deste projeto, integrar IA com qualquer dado fiscal brasileiro exigia desenvolvimento customizado, autenticação em múltiplos portais, e conhecimento profundo de cada API governamental. Cada consulta era um projeto.
  104. **MCP Fiscal Brasil** resolve isso em uma linha: instale o servidor, conecte ao seu assistente de IA, e comece a fazer perguntas em linguagem natural. O servidor cuida de tudo, consultando diretamente Receita Federal, BrasilAPI e SEFAZs estaduais.
  105. ---
  106. ## 🎬 Demonstração
  107. ```
  108. Você: "Consulte o CNPJ 00.000.000/0001-91 e liste os sócios"
  109. IA: Empresa: Banco do Brasil S.A.
  110. Fundada em: 12/10/1808
  111. Situação: ATIVA
  112. CNAE principal: 6422100 - Bancos múltiplos com carteira comercial
  113. Sócios (QSA):
  114. - União Federal - Sócio-Administrador (60,82%)
  115. - BNDESPar - Sócio (10,32%)
  116. ```
  117. ```
  118. Você: "A chave NFe 35240300623904000197550010000012341234567890 é válida?"
  119. IA: Chave válida!
  120. Estado de origem: SP (São Paulo)
  121. Data de emissão: março/2024
  122. CNPJ emitente: 00.623.904/0001-97
  123. Número da nota: 000001234
  124. Dígito verificador: correto (módulo 11)
  125. ```
  126. ```
  127. Você: "A empresa 12.345.678/0001-90 é do Simples Nacional?"
  128. IA: Sim! Empresa optante do Simples Nacional.
  129. Data de opção: 01/01/2020
  130. Modalidade: MEI - Microempreendedor Individual
  131. ```
  132. ```
  133. Você: "O SEFAZ de São Paulo está online agora?"
  134. IA: Status SEFAZ SP: OPERACIONAL
  135. Serviço de autorização de NFe funcionando normalmente.
  136. Última verificação: agora.
  137. ```
  138. ---
  139. ## 🛠 Ferramentas Disponíveis
  140. Ferramentas de baixo nível para dados fiscais e ferramentas agênticas de alto nível para decisão operacional.
  141. ### Tools agênticas
  142. | Ferramenta | Quando usar |
  143. |------------|-------------|
  144. | `analyze_cnpj_compliance` | Relatório consolidado de compliance fiscal de um CNPJ |
  145. | `risk_score_supplier` | Aprovar, investigar ou recusar fornecedor |
  146. | `consultar_empresas_lote` | Triar carteira de fornecedores com score e erro por CNPJ |
  147. | `compare_tax_regimes` | Comparar regimes tributários por cenário |
  148. | `validate_nfe_full` | Validar uma NFe completa a partir do XML |
  149. | `summarize_sped` | Transformar SPED em resumo executivo |
  150. ### ✅ Ferramentas Funcionais (usáveis agora)
  151. Funcionam 100% sem chaves de API. Instale e use imediatamente.
  152. | Módulo | Ferramenta | Descrição | API |
  153. |--------|-----------|-----------|-----|
  154. | CNPJ | `consultar_cnpj` | Dados completos: razão social, sócios, CNAE, endereço | BrasilAPI (grátis) + cpfcnpj.com.br (premium, opt-in) |
  155. | CNPJ | `consultar_simples_nacional` | Optante Simples/MEI com datas de entrada e exclusão | BrasilAPI (grátis) |
  156. | NFe | `validar_chave_nfe` | Valida dígito + extrai UF, CNPJ, data, número | Offline |
  157. | NFe | `consultar_nfe` | Consulta NFe completa pela chave de 44 dígitos | BrasilAPI (grátis) + cpfcnpj.com.br (premium, opt-in) |
  158. | NFe | `consultar_nfce` | NFC-e (modelo 65) pela chave de 44 dígitos; consulta completa exige token (pacote 102), senão tenta fontes públicas com dados parciais | cpfcnpj.com.br (pacote 102) + fontes públicas (parcial) |
  159. | NFe | `parse_nfe_xml` | Parseia XML bruto de NF-e/NFC-e e retorna dados estruturados | Offline |
  160. | NFe | `gerar_danfe` | Gera DANFE PDF (A4) a partir do XML de NF-e (mod 55) | Offline |
  161. | NFe | `validar_assinatura_nfe` | Valida assinatura XMLDSig e extrai dados do certificado | Offline |
  162. | NFe | `consultar_status_sefaz` | Status real do webservice SEFAZ por estado via NfeStatusServico4 (requer cert A1) | SEFAZ (mTLS) |
  163. | NFe | `baixar_nfe_distribuicao` | Baixa documentos via NFeDistribuicaoDFe (requer cert A1 local) | SEFAZ (mTLS) |
  164. | NFe | `manifestar_nfe` | Manifesta destinatario em NF-e via NFeRecepcaoEvento (requer cert A1) | SEFAZ (mTLS) |
  165. | CPF | `validar_cpf` | Validação de dígito verificador | Offline |
  166. | SPED | `analisar_sped` | Analisa arquivo EFD/ECD/ECF: período, empresa, erros | Offline |
  167. | SPED | `listar_registros_sped` | Filtra registros por tipo (C100, E110, etc.) | Offline |
  168. | eSocial | `listar_eventos_esocial` | Catálogo de eventos filtrável por grupo | Offline |
  169. | eSocial | `validar_evento_esocial` | Validação básica de estrutura XML | Offline |
  170. ---
  171. ### 🧭 Ferramentas de Orientação
  172. Retornam URLs e instruções - exigem ação manual nos portais governamentais.
  173. | Módulo | Ferramenta | O que retorna |
  174. |--------|-----------|--------------|
  175. | NFSe | `consultar_nfse` | URL do portal NFSe do município + sistema utilizado |
  176. | Certidões | `consultar_certidao_federal` | URL do e-CAC para emissão de CND federal |
  177. | Certidões | `consultar_certidao_fgts` | URL do portal Caixa para consulta do CRF |
  178. ---
  179. ### 🔐 Ferramentas com Certificado A1 (opt-in)
  180. As tools `baixar_nfe_distribuicao`, `manifestar_nfe` e `consultar_status_sefaz`
  181. requerem um certificado digital A1 (`.pfx`/`.p12`). mTLS é exigência de
  182. transporte de todo webservice SEFAZ, inclusive a consulta de status - não há
  183. como consultar o status real sem certificado.
  184. - O certificado e a senha **nunca são enviados a nenhum servidor externo**.
  185. - A autenticação mTLS e a assinatura XMLDSig são feitas localmente.
  186. - `baixar_nfe_distribuicao` e `manifestar_nfe` recebem o caminho do certificado
  187. como parâmetro da própria tool (`.pfx`/`.p12` local).
  188. - `consultar_status_sefaz` (via servidor MCP/API REST) usa o certificado
  189. configurado nas variáveis de ambiente abaixo, e se conecta ao webservice
  190. próprio da UF consultada ou ao ambiente virtual (SVRS/SVAN) quando a UF não
  191. tem infraestrutura própria.
  192. - As demais tools (parse, DANFE, assinatura, consultas de CNPJ/NFe via
  193. BrasilAPI) funcionam sem certificado.
  194. **Configuração** (variáveis em `.env` ou secret do provedor de deploy - ver
  195. `.env.example`):
  196. | Variável | Descrição |
  197. |----------|-----------|
  198. | `NFE_CERTIFICADO_PATH` | Caminho absoluto do `.pfx`/`.p12` montado no container |
  199. | `NFE_CERTIFICADO_SENHA` | Senha do certificado (sempre via gestor de segredos, nunca em `.env` versionado) |
  200. | `NFE_EMITENTE_CNPJ` | CNPJ do titular do certificado (14 dígitos, opcional) |
  201. | `NFE_AMBIENTE` | `producao` ou `homologacao` (padrão `producao`) |
  202. Sem `NFE_CERTIFICADO_PATH`/`NFE_CERTIFICADO_SENHA`, `consultar_status_sefaz`
  203. levanta `FiscalConfigurationError` e o endpoint HTTP `GET /v1/nfe/status-sefaz`
  204. responde 503 - o chamador deve tratar isso como "sem certificado configurado",
  205. não como SEFAZ fora do ar (falha pontual de rede em uma UF especifica, essa
  206. sim, degrada omitindo a UF em vez de derrubar a chamada). `GET
  207. /v1/fiscal/certificado/status` informa apenas se há certificado configurado e
  208. válido (sem titular nem CNPJ - endpoint sem autenticação, não deve permitir
  209. reconhecimento de identidade), sem nunca expor o arquivo ou a senha.
  210. ---
  211. ### ☁️ Provedor premium opcional: cpfcnpj.com.br (opt-in)
  212. O projeto continua **gratuito, sem cadastro e sem chave de API por padrão**. Para
  213. quem precisa de cobertura e atualidade de nível empresarial, a
  214. [cpfcnpj.com.br](https://www.cpfcnpj.com.br/dev/) pode ser habilitada como uma
  215. fonte premium **opt-in**, sem alterar em nada o comportamento gratuito padrão.
  216. Enquanto o token não é configurado, tudo funciona como antes, usando apenas as
  217. fontes gratuitas (BrasilAPI, ReceitaWS e Portal NFe). Ao definir `CPFCNPJ_TOKEN`,
  218. o provedor passa a ser consultado **primeiro**, e as fontes gratuitas seguem como
  219. fallback automático, de forma transparente.
  220. **O que a fonte premium acrescenta a este projeto fiscal:**
  221. - **Dados oficiais em tempo real (D+0):** cadastro atualizado direto na origem,
  222. sem depender de janelas de sincronização de bases intermediárias.
  223. - **Sem bases vazadas ou raspadas:** os dados vêm de fontes oficiais, com
  224. procedência conhecida, e não de dumps de terceiros.
  225. - **Conformidade com certificações internacionais** (ISO/IEC 27001 de segurança
  226. da informação, ISO/IEC 27701 de privacidade e ISO 37301 de gestão de
  227. conformidade), reforçando privacidade e tratamento adequado dos dados.
  228. - **Cobre a consulta de NF-e por chave**, que hoje depende de fontes públicas
  229. instáveis, e adiciona **NFC-e (modelo 65)**, ainda não coberta pelas APIs
  230. gratuitas.
  231. **Ferramentas cobertas quando o token está ativo:**
  232. | Ferramenta | Fonte premium | Pacote | Documentação |
  233. |-----------|---------------|--------|--------------|
  234. | `consultar_cnpj` | cpfcnpj.com.br | 5 ou 6 | [dev/](https://www.cpfcnpj.com.br/dev/) |
  235. | `consultar_nfe` | cpfcnpj.com.br | 100 (modelo 55) | [#op-get-token-100-chave](https://www.cpfcnpj.com.br/dev/#op-get-token-100-chave) |
  236. | `consultar_nfce` | cpfcnpj.com.br | 102 (modelo 65) | [#op-get-token-102-chave](https://www.cpfcnpj.com.br/dev/#op-get-token-102-chave) |
  237. O `consultar_nfce` retorna a NFC-e completa apenas com o token configurado (pacote
  238. 102). Sem token, ele recorre às fontes públicas e pode devolver dados parciais da
  239. chave. A cobertura on-line do pacote 102 está disponível em São Paulo (SP) e Minas
  240. Gerais (MG); as demais UFs exigem habilitação sob demanda e podem retornar o erro
  241. 204 (sem consumo de crédito). Detalhes de cobertura em
  242. [cpfcnpj.com.br/dev/](https://www.cpfcnpj.com.br/dev/).
  243. **Configuração** (todas opcionais, ver `.env.example`):
  244. | Variável | Descrição | Padrão |
  245. |----------|-----------|--------|
  246. | `CPFCNPJ_TOKEN` | Token da conta em cpfcnpj.com.br. **Vazio = fonte premium desligada.** | (vazio) |
  247. | `CPFCNPJ_BASE_URL` | URL base da API premium. Aceita somente `https://` (o token trafega no caminho da URL) | `https://api.cpfcnpj.com.br` |
  248. | `CPFCNPJ_CNPJ_PACKET` | Pacote de CNPJ: `5` (enxuto) ou `6` (completo) | `6` |
  249. Trate o token como segredo: use o gestor de segredos do seu provedor de deploy,
  250. nunca um `.env` versionado em produção.
  251. ---
  252. ### 🧪 Ferramentas Experimentais
  253. Requerem APIs pagas ou têm cobertura limitada.
  254. | Módulo | Ferramenta | Limitação |
  255. |--------|-----------|-----------|
  256. | CNPJ | `listar_cnpjs_por_nome` | Receita Federal não disponibiliza busca por nome em API pública |
  257. ---
  258. ## 🚀 Instalação
  259. A forma mais simples, sem instalar nada permanentemente:
  260. ```bash
  261. uvx mcp-fiscal-brasil
  262. ```
  263. > **O que é `uvx`?** É o gerenciador de ferramentas do [uv](https://docs.astral.sh/uv/), que baixa e executa pacotes Python em ambiente isolado, sem poluir seu sistema. Se ainda não tem o uv: `curl -LsSf https://astral.sh/uv/install.sh | sh`
  264. > **Mantendo atualizado via PyPI:** use `uvx mcp-fiscal-brasil@latest` ou `uvx --refresh mcp-fiscal-brasil` para forçar a versão mais recente. O `uvx` cacheia localmente, então sem `@latest` você pode continuar numa versão antiga.
  265. ---
  266. ## ⚙️ Configuração por Cliente MCP
  267. Cole o trecho abaixo no arquivo de configuração do seu cliente. **Nenhuma chave de API é necessária.**
  268. ### Claude Desktop
  269. Edite `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) ou `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
  270. ```json
  271. {
  272. "mcpServers": {
  273. "fiscal-brasil": {
  274. "command": "uvx",
  275. "args": ["mcp-fiscal-brasil"]
  276. }
  277. }
  278. }
  279. ```
  280. Reinicie o Claude Desktop. As ferramentas fiscais e agênticas aparecem automaticamente.
  281. ### Claude Code (CLI)
  282. ```bash
  283. claude mcp add fiscal-brasil -- uvx mcp-fiscal-brasil
  284. ```
  285. ### Cursor / `.mcp.json`
  286. Crie ou edite `.cursor/mcp.json` (ou `.mcp.json` na raiz do projeto):
  287. ```json
  288. {
  289. "mcpServers": {
  290. "fiscal-brasil": {
  291. "command": "uvx",
  292. "args": ["mcp-fiscal-brasil"]
  293. }
  294. }
  295. }
  296. ```
  297. ### VS Code + Continue
  298. Adicione ao `settings.json`:
  299. ```json
  300. {
  301. "continue.mcpServers": {
  302. "fiscal-brasil": {
  303. "command": "uvx",
  304. "args": ["mcp-fiscal-brasil"]
  305. }
  306. }
  307. }
  308. ```
  309. ### Docker
  310. ```bash
  311. docker run --rm -i \
  312. -e MCP_FISCAL_LOG_LEVEL=INFO \
  313. ghcr.io/dehor-labs/mcp-fiscal-brasil:latest
  314. ```
  315. ---
  316. ## 🛠 Instalação permanente (alternativa)
  317. Prefere instalar uma vez e manter no PATH?
  318. ```bash
  319. # via pip
  320. pip install mcp-fiscal-brasil
  321. # via uv (recomendado para projetos Python)
  322. uv add mcp-fiscal-brasil
  323. ```
  324. Após a instalação, os snippets JSON acima funcionam com `"command": "mcp-fiscal-brasil"` (sem o `uvx`).
  325. ### A partir do código-fonte
  326. ```bash
  327. git clone https://github.com/DeHor-Labs/mcp-fiscal-brasil.git
  328. cd mcp-fiscal-brasil
  329. pip install -e .
  330. ```
  331. ---
  332. ## 🔑 Variáveis de Ambiente
  333. Todas as variáveis são opcionais. O servidor funciona sem nenhuma configuração.
  334. | Variável | Descrição | Padrão |
  335. |----------|-----------|--------|
  336. | `MCP_FISCAL_LOG_LEVEL` | Nível de log: `DEBUG`, `INFO`, `WARNING` | `INFO` |
  337. | `BRASILAPI_BASE_URL` | URL base da BrasilAPI (para ambientes customizados) | `https://brasilapi.com.br/api` |
  338. | `HTTP_TIMEOUT` | Timeout em segundos para chamadas HTTP | `30` |
  339. | `CPFCNPJ_TOKEN` | Token do provedor premium opt-in [cpfcnpj.com.br](https://www.cpfcnpj.com.br/dev/). Vazio = desligado (padrão gratuito intacto) | (vazio) |
  340. | `CPFCNPJ_BASE_URL` | URL base da API premium cpfcnpj.com.br. Aceita somente `https://` | `https://api.cpfcnpj.com.br` |
  341. | `CPFCNPJ_CNPJ_PACKET` | Pacote de CNPJ na cpfcnpj.com.br: `5` ou `6` | `6` |
  342. ---
  343. ## Modos de Uso
  344. O `mcp-fiscal-brasil` funciona de quatro formas:
  345. | Modo | Para quem | Como |
  346. |------|-----------|------|
  347. | **MCP Server** | Usuários de IA (Claude, Cursor, GPT) | Instala e configura no assistente |
  348. | **SDK Python** | Desenvolvedores de apps fiscais/contábeis | Importa e usa no código |
  349. | **CLI** | Operação, scripts e automações locais | Usa `mcp-fiscal ...` |
  350. | **REST API + Web UI** | Integração HTTP e demo pública | Usa `mcp-fiscal-api` |
  351. ---
  352. ## 🐍 Uso como Biblioteca Python (SDK)
  353. Além de funcionar como servidor MCP, você pode importar e usar diretamente no seu código Python - sem servidor, sem configuração extra.
  354. ### Início Rápido
  355. ```python
  356. import asyncio
  357. from mcp_fiscal_brasil import FiscalBrasil
  358. async def main():
  359. async with FiscalBrasil() as fiscal:
  360. empresa = await fiscal.consultar_cnpj("00.000.000/0001-91")
  361. print(empresa["razao_social"]) # Banco do Brasil S.A.
  362. print(empresa["situacao_cadastral"]) # ATIVA
  363. asyncio.run(main())
  364. ```
  365. ### Validações Offline (sem API, instantâneo)
  366. ```python
  367. from mcp_fiscal_brasil import FiscalBrasil
  368. fiscal = FiscalBrasil()
  369. # Validações locais - sem chamada de rede
  370. print(fiscal.validate_cpf("529.982.247-25")) # True
  371. print(fiscal.validate_cnpj("11.222.333/0001-81")) # True / False
  372. print(fiscal.validate_chave_nfe("3524...44 digitos...")) # dict com detalhes
  373. ```
  374. ### Integração com FastAPI
  375. ```python
  376. from fastapi import FastAPI
  377. from mcp_fiscal_brasil import FiscalBrasil
  378. app = FastAPI()
  379. fiscal = FiscalBrasil()
  380. @app.get("/cnpj/{cnpj}")
  381. async def consultar(cnpj: str):
  382. async with fiscal:
  383. return await fiscal.consultar_cnpj(cnpj)
  384. ```
  385. ### Integração com Django
  386. ```python
  387. # views.py
  388. import asyncio
  389. from mcp_fiscal_brasil import FiscalBrasil
  390. from django.http import JsonResponse
  391. def consulta_cnpj(request, cnpj):
  392. async def buscar():
  393. async with FiscalBrasil() as fiscal:
  394. return await fiscal.consultar_cnpj(cnpj)
  395. dados = asyncio.run(buscar())
  396. return JsonResponse(dados)
  397. ```
  398. ### Cadastro Automático de Fornecedor (exemplo ERP)
  399. ```python
  400. import asyncio
  401. from mcp_fiscal_brasil import FiscalBrasil
  402. async def cadastrar_fornecedor(cnpj: str, db_session):
  403. async with FiscalBrasil() as fiscal:
  404. if not fiscal.validate_cnpj(cnpj):
  405. raise ValueError("CNPJ inválido")
  406. dados = await fiscal.consultar_cnpj(cnpj)
  407. simples = await fiscal.consultar_simples_nacional(cnpj)
  408. await db_session.execute(
  409. "INSERT INTO fornecedores (cnpj, razao_social, simples) VALUES (?, ?, ?)",
  410. [cnpj, dados["razao_social"], simples["optante"]]
  411. )
  412. ```
  413. ### Validação em Lote
  414. ```python
  415. import asyncio
  416. from mcp_fiscal_brasil import FiscalBrasil
  417. fiscal = FiscalBrasil()
  418. documentos = ["529.982.247-25", "000.000.000-00", "11.222.333/0001-81"]
  419. resultados = [
  420. {"doc": doc, "válido": fiscal.validate_cpf(doc) or fiscal.validate_cnpj(doc)}
  421. for doc in documentos
  422. ]
  423. # [{'doc': '529.982.247-25', 'válido': True}, ...]
  424. ```
  425. ---
  426. ## 🏗 Arquitetura
  427. ```
  428. Claude / GPT / Cursor / qualquer cliente MCP
  429. |
  430. | Model Context Protocol (stdio)
  431. v
  432. mcp-fiscal-brasil
  433. |
  434. +------+-------+--------+--------+--------+-------+--------+
  435. | | | | | | | |
  436. CNPJ CPF NFe NFSe Simples SPED eSocial Certidões
  437. | | | | | | | |
  438. v v v v v v v v
  439. BrasilAPI -- SEFAZ Portais Receita Parser Catálogo URLs
  440. ReceitaWS estaduais municipais Federal local local governamentais
  441. ```
  442. **Fontes de dados:**
  443. - [BrasilAPI](https://brasilapi.com.br) - CNPJ, CEP, bancos (open source, sem autenticação)
  444. - [ReceitaWS](https://www.receitaws.com.br) - CNPJ (fallback)
  445. - SEFAZs estaduais - Status de serviço e consulta de NFe
  446. - Receita Federal - Simples Nacional e certidões (orientação de acesso)
  447. ---
  448. ## 📍 Roadmap
  449. - [x] **v0.1.x** - Consultas CNPJ, CPF, NFe, Simples Nacional e SPED; ~14 tools MCP
  450. - [x] **v0.2.x** - Infra production-grade (_core), CLI, REST API, Web UI demo, wrapper npm/Node.js e tools agênticas (compliance, due diligence, comparativo de regimes); ~20 tools MCP
  451. - [x] **v0.3.x** - Tabelas fiscais offline (NCM/TIPI, CFOP, CST, CEST, ICMS interestadual) e indexadores BCB (Selic, IPCA, PTAX, correção monetária); ~36 tools MCP
  452. - [x] **v0.4.x** - Módulo NF-e completo (parse, DANFE, assinatura XMLDSig, distribuição mTLS, manifestação do destinatário) e simulador da Reforma Tributária IBS/CBS (LC 214/2025); ~42 tools MCP
  453. - [x] **v0.5.x** - Módulo de importação (II, IPI, PIS/COFINS-importação, ICMS grossed-up, AFRMM, Siscomex) por NCM; circuit breaker NFS-e; correções SPED e path injection; automação de release; 45 tools MCP
  454. - [ ] **v0.6.x** - NFC-e modelo 65 (DANFE cupom, autorizacao e cancelamento); NFS-e por provedor/municipio; validação XSD completa NF-e e SPED
  455. - [ ] **v0.7.x** - eSocial versionado (S-1.1); cache persistente entre sessões; LGPD audit trail
  456. - [ ] **v1.0.0** - Suíte fiscal com contratos de API estáveis, cobertura operacional ampliada e SLA de manutenção documentado
  457. ---
  458. ## Como acompanhar
  459. [![GitHub Discussions](https://img.shields.io/github/discussions/DeHor-Labs/mcp-fiscal-brasil)](https://github.com/DeHor-Labs/mcp-fiscal-brasil/discussions)
  460. [![GitHub Stars](https://img.shields.io/github/stars/DeHor-Labs/mcp-fiscal-brasil)](https://github.com/DeHor-Labs/mcp-fiscal-brasil/stargazers)
  461. <a href="https://star-history.com/#DeHor-Labs/mcp-fiscal-brasil&Date">
  462. <picture>
  463. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=DeHor-Labs/mcp-fiscal-brasil&type=Date&theme=dark" />
  464. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=DeHor-Labs/mcp-fiscal-brasil&type=Date" />
  465. <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=DeHor-Labs/mcp-fiscal-brasil&type=Date" />
  466. </picture>
  467. </a>
  468. - **Releases**: clique em **Watch -> Releases** no topo do repositório para ser notificado a cada versão nova
  469. - **Discussions**: [github.com/DeHor-Labs/mcp-fiscal-brasil/discussions](https://github.com/DeHor-Labs/mcp-fiscal-brasil/discussions) - canal para sugestões de feature, dúvidas fiscais e técnicas, e casos de uso. Sugestões feitas aqui entram no roadmap de verdade
  470. - **Newsletter**: acompanhe os releases comentados na [LinkedIn Newsletter MCP Fiscal Brasil](https://www.linkedin.com/newsletters/7474668338875494400/) - cada edição explica o que chegou, o que foi corrigido e o que vem por ai. [Assinar agora](https://www.linkedin.com/build-relation/newsletter-follow?entityUrn=7474668338875494400)
  471. - **Issues**: bugs com contexto completo (versão, XML de exemplo sem dados reais, comportamento esperado vs. obtido)
  472. ---
  473. ## 🤝 Contribuindo
  474. Contribuições são bem-vindas!
  475. ```bash
  476. # 1. Clone o repo ou seu fork
  477. git clone https://github.com/DeHor-Labs/mcp-fiscal-brasil.git
  478. cd mcp-fiscal-brasil
  479. # 2. Instale dependências de desenvolvimento
  480. pip install -e ".[dev]"
  481. pre-commit install
  482. # 3. Crie sua branch
  483. git checkout -b feature/meu-recurso
  484. # 4. Implemente, teste e verifique
  485. python scripts/check_release_metadata.py
  486. ruff check src/ tests/
  487. ruff format --check src/ tests/
  488. mypy src/
  489. pytest
  490. # 5. Abra um Pull Request
  491. ```
  492. Veja as [issues abertas](https://github.com/DeHor-Labs/mcp-fiscal-brasil/issues) - especialmente as marcadas com `good first issue`.
  493. Cada módulo segue o padrão `client.py` + `schemas.py` + `tools.py`, o que torna simples adicionar novos módulos fiscais.
  494. ---
  495. ## 📄 Licença
  496. MIT - veja [LICENSE](LICENSE) para detalhes.
  497. ---
  498. <p align="center">
  499. Feito com 💚💛 para o Brasil
  500. <br>
  501. <sub>Conectando inteligência artificial ao sistema fiscal mais complexo do mundo</sub>
  502. </p>

Ratings and comments

Sign in to rate this skill.

Sign in

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