BrasilAPI (CNPJ, CEP, validation, holidays)

brasilapi-mcp

一个 MCP 服务，通过 BrasilAPI 为 AI 助手提供巴西公共数据：按 CNPJ 查询公司注册信息（包括合伙人）、按 CEP 查询地址、离线验证 CNPJ/CPF，以及查询全国节假日。

该项目源于公司尽职调查（KYC）工作流的实践经验：Agent 需要核实公司是否存在、是否处于正常状态以及合伙人是谁，并且不能信任未通过校验位验证的号码。本项目独立开发，与 BrasilAPI 或 Receita Federal 均无关联。

工具

工具	功能	网络
lookup_cnpj	查询公司的法定名称、注册状态、主营业务、地址、规模、税务制度和合伙人（QSA）。支持带或不带标点的数字或字母数字格式 CNPJ。	BrasilAPI
validate_cnpj	检查数字和字母数字格式 CNPJ 的格式及校验位。	无
validate_cpf	检查 CPF 的格式及校验位。不会存储或发送任何内容。	无
lookup_cep	查询 CEP 对应的街道、街区、城市、州、IBGE 代码和坐标。	BrasilAPI
list_holidays	查询某一年的全国节假日及其星期几。	BrasilAPI

lookup_cnpj 会在发出任何请求前拒绝校验位错误的号码，因此输入错误不会产生任何成本，也不会将号码发送到 API。注册机构会对合伙人的 CPF 进行掩码处理（***123456**）；服务不会尝试还原或存储任何内容。

示例：使用 lookup_cnpj 并设置 include_partners: false：

{
  "cnpj": "00000000000191",
  "razaoSocial": "BANCO DO BRASIL SA",
  "situacaoCadastral": { "descricao": "ATIVA", "desde": "2005-11-03", "motivo": "SEM MOTIVO" },
  "tipo": "MATRIZ",
  "naturezaJuridica": "Sociedade de Economia Mista",
  "cnaePrincipal": { "codigo": 6422100, "descricao": "Bancos múltiplos, com carteira comercial" },
  "endereco": { "municipio": "BRASILIA", "uf": "DF", "cep": "70040912", "...": "..." },
  "totalSocios": 41
}

安装

需要 Node 20 或更高版本。

Claude Code：

claude mcp add brasilapi -- npx -y @renatoctti/brasilapi-mcp

Claude Desktop、Cursor 及其他读取 mcpServers 配置块的客户端：

{
  "mcpServers": {
    "brasilapi": {
      "command": "npx",
      "args": ["-y", "@renatoctti/brasilapi-mcp"]
    }
  }
}

从源代码安装：

git clone https://github.com/renatoctti/brasilapi-mcp
cd brasilapi-mcp
npm install
npm run build
node dist/src/index.js   # speaks MCP over stdio

说明

• 数据来源。 BrasilAPI 是一项聚合公共数据的免费社区服务。该服务有速率限制；遇到 429 错误时，服务会用通俗文字报告错误，而不会重试。每个请求的超时时间为 10 秒。
• 身份标识。 BrasilAPI 位于防火墙之后，会拒绝来自默认匿名 HTTP Agent 的请求，因此每个请求都会携带 User-Agent: brasilapi-mcp/<version> (+repo url)。
• 字母数字格式 CNPJ。 自 2026 年起，Receita Federal 开始签发包含字母的 CNPJ。验证器遵循已公布的校验位规则（字符值为其 ASCII 码减 48）。能否查询到公司取决于 BrasilAPI 是否收录该公司。
• 数据时效性。 注册数据可能比 Receita Federal 延迟数天。应将其视为初步核查，而非证明文件。
• 无状态。 服务不会在调用之间保留任何内容，也不会记录所查询号码的日志；标准错误输出中唯一的内容是启动信息。

开发

npm test        # builds, then runs the unit and protocol tests (no network)
npm run smoke   # starts the built server over stdio and calls every tool on the real API

测试覆盖校验位规则（数字和字母数字格式 CNPJ、CPF）、各类答复的转换、错误场景（未找到、速率限制、无法连接），以及通过内存 MCP 客户端对服务本身的测试；测试中使用模拟的 fetch 代替 BrasilAPI。

许可证

MIT