MCP Fiscal Brasil

O primeiro servidor MCP para o sistema fiscal brasileiro

Instalação · Ferramentas · Exemplos · Roadmap · Contribuindo

______________________________________________________________________

为什么这个项目存在？

巴西拥有世界上最复杂的税收制度。它们 27个经济特区 国家， NFe+NFSe+SPED+eSocial每个城市都有自己的服务门户网站，以及更多 500英里中小企业 每天都在努力保持税务合规性。

在这个项目之前，将人工智能与任何巴西税务数据集成需要定制开发，多门户认证以及对每个政府API的深入了解。每个咨询都是一个项目。

MCP 巴西 税务 解决这个问题：安装服务器，连接到您的人工智能助理，并开始用自然语言提问。服务器通过直接咨询联邦税务局，巴西API和州SEFAZ来处理一切。

______________________________________________________________________

🎬 演示

Você:  "Consulte o CNPJ 00.000.000/0001-91 e liste os sócios"

IA:    Empresa: Banco do Brasil S.A.
       Fundada em: 12/10/1808
       Situação: ATIVA
       CNAE principal: 6422100 - Bancos múltiplos com carteira comercial

       Sócios (QSA):
       - União Federal - Sócio-Administrador (60,82%)
       - BNDESPar - Sócio (10,32%)

Você:  "A chave NFe 35240300623904000197550010000012341234567890 é válida?"

IA:    Chave válida!
       Estado de origem: SP (São Paulo)
       Data de emissão: março/2024
       CNPJ emitente: 00.623.904/0001-97
       Número da nota: 000001234
       Dígito verificador: correto (módulo 11)

Você:  "A empresa 12.345.678/0001-90 é do Simples Nacional?"

IA:    Sim! Empresa optante do Simples Nacional.
       Data de opção: 01/01/2020
       Modalidade: MEI - Microempreendedor Individual

Você:  "O SEFAZ de São Paulo está online agora?"

IA:    Status SEFAZ SP: OPERACIONAL
       Serviço de autorização de NFe funcionando normalmente.
       Última verificação: agora.

______________________________________________________________________

🛠 可用工具

14 工具 涵盖巴西税收制度的主要模块。

______________________________________________________________________

✅ 功能工具（ 现在可用）

100%无需API密钥。立即安装并使用。

NFE 。 consultar_nfe 查询完整的 NFe 44位密钥 BrasilAPI （免费） |CPF| validar_cpf | 数字验证 | 离线 | |加速| analisar_sped | 分析 EFD/ECD/ECF 档案：期间、公司、错误 | 离线 | |加速| listar_registros_sped |按类型过滤记录（C100、E110等）|离线| |深奥的| listar_eventos_esocial | 按组过滤的事件目录 | 离线 | |深奥的| validar_evento_esocial | 基本 XML 结构验证 | 离线 |

______________________________________________________________________

🧭 指导工具

返回URL和指令 - 需要在政府门户上手动操作。

______________________________________________________________________

🧪 实验工具

需要付费 API 或覆盖范围有限。

______________________________________________________________________

🚀 安装

三行开始：

pip install mcp-fiscal-brasil
claude mcp add fiscal-brasil -- mcp-fiscal-brasil
# Pronto! Pergunte ao Claude sobre qualquer empresa brasileira.

# Ou use como biblioteca Python:
from mcp_fiscal_brasil import FiscalBrasil

通过紫外线（推荐）

uv add mcp-fiscal-brasil

从源代码

git clone https://github.com/nikolasdehor/mcp-fiscal-brasil.git
cd mcp-fiscal-brasil
pip install -e .

______________________________________________________________________

⚙️ 详细设置

克劳德桌面

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "fiscal-brasil": {
      "command": "mcp-fiscal-brasil"
    }
  }
}

重新启动 Claude Desktop。所有14种税收工具都会自动出现。

克劳德代码（CLI）

claude mcp add fiscal-brasil -- mcp-fiscal-brasil

光标

添加到 .cursor/mcp.json 项目 ：

{
  "mcpServers": {
    "fiscal-brasil": {
      "command": "mcp-fiscal-brasil"
    }
  }
}

VS代码+继续

添加到 settings.json:

{
  "continue.mcpServers": {
    "fiscal-brasil": {
      "command": "mcp-fiscal-brasil"
    }
  }
}

码头工人

docker run --rm -i \
  -e MCP_FISCAL_LOG_LEVEL=INFO \
  ghcr.io/nikolasdehor/mcp-fiscal-brasil:latest

______________________________________________________________________

🔑 环境变量

所有变量都是可选的。服务器在没有配置的情况下工作 。

______________________________________________________________________

两种使用方式

mcp-fiscal-brasil是由 两种形式:

______________________________________________________________________

🐍 用作Python库（SDK）

除了充当MCP服务器外，您还可以直接导入和使用Python代码 - 无需服务器，无需额外配置。

快速入门

import asyncio
from mcp_fiscal_brasil import FiscalBrasil

async def main():
    async with FiscalBrasil() as fiscal:
        empresa = await fiscal.consultar_cnpj("00.000.000/0001-91")
        print(empresa["razao_social"])  # Banco do Brasil S.A.
        print(empresa["situacao_cadastral"])  # ATIVA

asyncio.run(main())

离线验证（无API，即时）

from mcp_fiscal_brasil import FiscalBrasil

fiscal = FiscalBrasil()

# Validações locais - sem chamada de rede
print(fiscal.validate_cpf("529.982.247-25"))       # True
print(fiscal.validate_cnpj("11.222.333/0001-81"))  # True / False
print(fiscal.validate_chave_nfe("3524...44 digitos..."))  # dict com detalhes

与FastAPI集成

from fastapi import FastAPI
from mcp_fiscal_brasil import FiscalBrasil

app = FastAPI()
fiscal = FiscalBrasil()

@app.get("/cnpj/{cnpj}")
async def consultar(cnpj: str):
    async with fiscal:
        return await fiscal.consultar_cnpj(cnpj)

与 Django 集成

# views.py
import asyncio
from mcp_fiscal_brasil import FiscalBrasil
from django.http import JsonResponse

def consulta_cnpj(request, cnpj):
    async def buscar():
        async with FiscalBrasil() as fiscal:
            return await fiscal.consultar_cnpj(cnpj)
    dados = asyncio.run(buscar())
    return JsonResponse(dados)

自动供应商注册（例如ERP）

import asyncio
from mcp_fiscal_brasil import FiscalBrasil

async def cadastrar_fornecedor(cnpj: str, db_session):
    async with FiscalBrasil() as fiscal:
        if not fiscal.validate_cnpj(cnpj):
            raise ValueError("CNPJ inválido")

        dados = await fiscal.consultar_cnpj(cnpj)
        simples = await fiscal.consultar_simples_nacional(cnpj)

        await db_session.execute(
            "INSERT INTO fornecedores (cnpj, razao_social, simples) VALUES (?, ?, ?)",
            [cnpj, dados["razao_social"], simples["optante"]]
        )

批量验证

import asyncio
from mcp_fiscal_brasil import FiscalBrasil

fiscal = FiscalBrasil()

documentos = ["529.982.247-25", "000.000.000-00", "11.222.333/0001-81"]

resultados = [
    {"doc": doc, "valido": fiscal.validate_cpf(doc) or fiscal.validate_cnpj(doc)}
    for doc in documentos
]
# [{'doc': '529.982.247-25', 'valido': True}, ...]

______________________________________________________________________

🏗 建筑

Claude / GPT / Cursor / qualquer cliente MCP
           |
           | Model Context Protocol (stdio)
           v
    mcp-fiscal-brasil
           |
    +------+-------+--------+--------+--------+-------+--------+
    |      |       |        |        |        |       |        |
   CNPJ   CPF    NFe      NFSe   Simples    SPED  eSocial Certidões
    |      |       |        |        |        |       |        |
    v      v       v        v        v        v       v        v
BrasilAPI  --   SEFAZ   Portais   Receita  Parser  Catálogo  URLs
ReceitaWS       estaduais municipais Federal  local   local  governamentais

数据源 ：

• %s（%s） CNPJ，CEP，银行（开源，无身份验证）
• 食谱WS -CNPJ（后备）
• 州级SEFAZs - 服务状态和NFe查询
• 联邦税收 - 简单的国家和认证（访问指南）

______________________________________________________________________

📍 路线图

• \[x\] v0.1.0 - 查询CNPJ，CPF，NFe，简单，SPED（当前）
• \[ \] v0.2.0版本 - NFSe 50+市，完整的eSocial目录
• \[ \] v0.3.0 发行NFe/NFSe（需要A1数字证书）
• \[ \] v1.0.0 -eSocial completo、LGPD审计、合规套件

______________________________________________________________________

🤝 贡献

欢迎捐款！

# 1. Fork e clone
git clone https://github.com/SEU_USUARIO/mcp-fiscal-brasil.git
cd mcp-fiscal-brasil

# 2. Instale dependências de desenvolvimento
pip install -e ".[dev]"
pre-commit install

# 3. Crie sua branch
git checkout -b feature/meu-recurso

# 4. Implemente, teste e verifique
pytest
ruff check src/
mypy src/

# 5. Abra um Pull Request

查看 异常问题 尤其是标有 good first issue.

每个模块都遵循标准 client.py + schemas.py + tools.py这使得添加新的税务模块变得容易。

______________________________________________________________________

📄 许可证

麻省 理工 学院 公路 许可证 为了细节。

______________________________________________________________________

Feito com 💚💛 para o Brasil

Conectando inteligência artificial ao sistema fiscal mais complexo do mundo