Peru Sunat Ruc

@pipeworx/peru-sunat-ruc

秘鲁 SUNAT（税务机关）的纳税人登记册“Padron reducido del RUC”：包含所有 11 位数的公司 RUC、注册名称（razon social）、纳税人状态（正常、注销、暂停等）、住所状况（habido / no habido 等），以及法人实体的注册地址和 INEI ubigeo 代码。 截至 2026-10-29 版，约有 237 万条公司和政府机关 RUC 记录（不包括个人）。

属于 Pipeworx — 一个将 AI Agent 连接到 1863+ 个实时数据源的 MCP 网关。这是独立的非官方集成，与上游提供方无关联、未获其认可，也非由其发布。

latam-validate 只检查 RUC 格式；此工具包可查询 RUC 是否在 SUNAT 登记册中，以及其状态。

工具

• pe_ruc(ruc) — 根据 11 位数 RUC 查询一名纳税人。若 found: false，会返回 reason（bad_format，或 not_in_register 及 check_digit_valid）和 data_as_of，绝不会返回空对象。
• pe_ruc_search(name, ubigeo?, active_only?, limit?) — 对法人实体进行忽略重音符号的名称搜索（所有长度为 3 个或以上字母的词都必须出现），优先显示有效登记记录；可选按 ubigeo 前缀筛选（2 位 = 省，4 位 = 市，6 位 = 区）。

每个响应都包含 data_as_of 和 source。状态和住所状况按 SUNAT 发布时的内容返回（发布方会将标签截断为 20 个字符，例如 BAJA PROV. POR OFICI），旁边附有尽力提供的英文释义。

不包括自然人

此工具包仅涵盖公司和组织（RUC 前缀为 20，以及前缀为 00 的政府机关；约 237 万条登记记录）。个人（RUC 以 10、15、17 开头，约占登记册的 1610 万条记录）不会存储、查询或搜索 — Bruce 裁定，2026-10-29。对个人 RUC 调用 pe_ruc 时，仅根据 RUC 前缀返回 found: false, reason: "natural_person_not_served"，不会读取数据库，也不会泄露姓名、状态或该号码是否存在。加载器会在写入前丢弃这些前缀的记录。

身份验证

无需密钥。这些工具仅可通过 Pipeworx 网关使用（登记册存储在网关侧数据库中）；独立安装会明确返回 StoreUnavailableError，绝不会返回空结果。

数据来源与再利用条款

• SUNAT（Superintendencia Nacional de Aduanas y de Administracion Tributaria，秘鲁），“Padron reducido del RUC”，以每日更新的批量文件形式发布（页面标注“Actualizado al DD/MM/YYYY”）。每个响应中的 data_as_of 都是已加载版本对应的该日期。仅 scripts/peru-sunat-ruc/ 中包含获取机制（该目录不对外发布，参见 CLAUDE.md 第 9b 步）。
• 未公布再利用条款。 发布方的下载页面（2026-10-29 读取）仅包含标题“Padron Reducido”、日期“(Actualizado al 29/10/2026)”和两个下载链接；页面没有许可证、使用条款或再分发声明。这是向任何人公开提供、无需凭据即可获取的秘鲁公共税务登记数据，且没有禁止再分发的规定，因此予以提供 — 此处标明未明确授予再利用权。

刷新

bash scripts/peru-sunat-ruc/refresh.sh load 会下载该版本并构建本地 SQLite 文件（ISO-8859-1 编码，以 | 分隔，\| 用于转义字面量竖线；若状态未知、行格式错误或下载不完整，则会明确报错），替换 D1 表，分批填充三元组名称索引，并断言索引已完整建立。refresh.sh verify 为只读操作；verify --self-test 可证明完整性检查机制能够失败。

快速开始

添加到你的 MCP 客户端（Claude Desktop、Cursor、Windsurf 等）：

{
  "mcpServers": {
    "peru-sunat-ruc": {
      "url": "https://gateway.pipeworx.io/peru-sunat-ruc/mcp"
    }
  }
}

此端点实际提供的内容

tools/list 在 https://gateway.pipeworx.io/peru-sunat-ruc/mcp 返回上表中的工具，以及 Pipeworx 的共享元工具——ask_pipeworx、 discover_tools、search_within、remember/recall 和网关范围内的其他工具。因此，你看到的工具数量会多于表格中的数量：目前，单个工具包端点除了列出该工具包自己的工具，还会列出大约 30 个共享工具。连接的 initialize 响应会说明其准确范围，并且是当天有效范围的权威答案。

这是有意设计的，并非意外的多路复用。元工具让作用域受限的连接能够回答此工具包未涵盖的问题——通过 ask_pipeworx 在整个目录中进行路由——而无需添加第二个 MCP 服务。目前无法挂载不含这些元工具的工具包端点；如果额外的架构定义比路由带来的价值更占上下文，不妨只连接一次完整网关，而不是连接多个工具包端点。

你也可以连接完整的 Pipeworx 网关，直接列出所有工具包的工具，而不只是此工具包的工具：

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

两个 URL 都会连接到同一个网关和相同的 1863+ 个数据源。唯一的区别是直接列出哪个工具包的工具；无论连接哪个端点，ask_pipeworx 都能访问所有工具。

没有 MCP 客户端？通过 HTTP 调用

curl -X POST https://gateway.pipeworx.io/v1/tools/pe_ruc \
  -H 'Content-Type: application/json' \
  -d '{"ruc":"20100070970"}'

首次调用无需账户。查看任意工具：GET https://gateway.pipeworx.io/v1/tools/pe_ruc。查找工具：使用 {"query":"..."} 调用 POST https://gateway.pipeworx.io/v1/tools/search_packs。

从 npm 运行

@pipeworx/mcp-peru-sunat-ruc 是连接 Pipeworx 网关的本地 stdio 桥接程序：你的 MCP 客户端使用 npx 启动它，然后它会将每次调用转发到上文所示的同一端点 https://gateway.pipeworx.io/peru-sunat-ruc/mcp。它需要网络访问；不支持离线模式。

{
  "mcpServers": {
    "peru-sunat-ruc": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-peru-sunat-ruc"]
    }
  }
}

不使用密钥时，它会匿名调用，每天最多 50 次。免费账户可将上限提高到每天 200 次：在 https://pipeworx.io/signup 获取密钥，并将 "env": { "PIPEWORX_API_KEY": "<your key>" } 添加到服务条目中。 密钥会像托管连接一样作为 Bearer 令牌发送，因此调用会按与托管连接完全相同的方式计量和计费。

默认情况下，它仅列出此工具包的工具。设置 PIPEWORX_META_TOOLS=1，还可列出 ask_pipeworx 和其他网关范围内的工具。

使用 HTTPS 代理时：Node 内置的 fetch 默认不会读取 HTTPS_PROXY。较新版本的 Node 在设置 NODE_USE_ENV_PROXY=1 后会遵循该变量；请查看对应 Node 版本的文档。

使用 ask_pipeworx

你可以用自然语言提问，而不是直接调用工具——完整网关和上面的工具包端点都支持此功能：

ask_pipeworx({ question: "your question about Peru Sunat Ruc data" })

网关会自动选择合适的工具并填入参数。

更多信息

• 文档和指南
• pipeworx.io

许可证

MIT