Ares (czech Business Registry) Mcp — Ares Mcp

ares-mcp

面向 ARES（捷克商业登记处）的 MCP 服务。 可直接通过 Claude Desktop、Claude Code、Cursor 和其他兼容 MCP 的客户端，验证 IČO/DIČ、查询公司、法定机构、营业执照和地址。

开源（MIT），可自托管。 通过捷克公共 ARES API 运行——查询不会离开你的设备。还可选择生成 Ed25519 签名的、注明来源的答复，任何人都能离线验证其完整性和来源。

托管版本： icovazby.cz——覆盖 10 多个捷克登记处（ARES、公共登记处、营业执照、破产、制裁等）的完整网页版公司核查服务。

ARES（Administrativní registr ekonomických subjektů，经济主体行政登记处）是捷克官方公共企业登记处，由捷克财政部（MFČR）运营。本项目是一个由社区独立构建的 MCP 服务，调用公共 ARES REST API。

与捷克财政部无关联。 本项目与 MFČR 或 ARES 运营方无关联、未获其认可或赞助。“ARES”指公共信息系统；此 MCP 服务是第三方软件。

• 免费，采用 MIT 许可的代码。 无需 API 密钥（ARES 是公共 API）。
• 14 个稳定工具，覆盖完整的尽职调查和开票工作流：验证、查询、结构化搜索、按地址搜索（检测虚拟办公室）、法定机构、营业执照、增值税检查、地址标准化、NACE 查询、RES 统计分类（规模区间、ESA 2010 行业）、破产检查、带 Mermaid 的跨公司人员关系图，并可选择启用历史模式以检测名义代持人；还有一个一次性调用的 ares_full_due_diligence 宏，提供 🟢🟡🔴 风险标记，以及一个导出适配器，可生成可直接 POST 的 Fakturoid / iDoklad / Pohoda 载荷。
• 两种传输方式。 Stdio（默认），适用于本地 AI 客户端；Streamable HTTP（/mcp），适用于远程 / Web 部署。
• 可验证的来源信息（可选）。 设置签名密钥后，尽职调查、法定机构和破产检查工具会返回签名信封，每条事实都附有登记处来源和日期；可通过已发布的 JWKS 离线验证。这是技术性的完整性和来源证明，并非合格电子签名或官方摘录。
• 防御性设计。 可感知速率限制（令牌桶 + 带 Retry-After 的指数退避）；HTTP 版本按 IP 节流请求；提供结构化错误；默认不存储或记录个人身份信息。

---

设置

运行 ares-mcp 有两种方式——任选一种：

选项 A — npx（无需安装，推荐）

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

选项 B — 从源代码运行

git clone [email protected]:milos106/ares-mcp.git
cd ares-mcp
npm install
npm run build
npm test

然后将 MCP 客户端指向 dist/index.js 的绝对路径。下面各客户端的示例使用从源代码运行的方式——如果你更希望采用零安装配置，可将 "command": "node", "args": ["…/dist/index.js"] 替换为上方的 npx 配置。

Claude Desktop

编辑你的 claude_desktop_config.json：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ares": {
      "command": "node",
      "args": ["/absolute/path/to/ares-mcp/dist/index.js"]
    }
  }
}

重启 Claude Desktop。

Claude Code

claude mcp add ares -- node /absolute/path/to/ares-mcp/dist/index.js

Cursor

在 Cursor 设置 → MCP 服务中：

{
  "ares": {
    "command": "node",
    "args": ["/absolute/path/to/ares-mcp/dist/index.js"]
  }
}

获取可直接粘贴的客户端配置

运行 npm run build 后，此命令会输出适用于 Claude Desktop、Cursor、Claude Code 和本地 HTTP 传输的绝对路径配置块：

npm run config

将 JSON 配置块直接复制到客户端的 MCP 配置中——无需编辑路径。

使用 MCP Inspector 交互式试用

npm run inspector

（等同于 npx @modelcontextprotocol/inspector node dist/index.js。）

浏览器会打开 http://localhost:6274，你可以在其中列出工具、填写参数，并对接实时 ARES 运行工具——无需配置客户端。

作为本地 HTTP 服务运行

另一个入口通过 MCP Streamable HTTP 提供相同的工具。适合在多个本地客户端间共享同一个运行中的实例。

PORT=3030 npm run start:http

端点：

• POST /mcp — Streamable HTTP 传输（通过 HTTP / SSE 传输 JSON-RPC）
• GET /healthz — 存活状态 + 会话数量

通过环境变量进行配置：

变量	默认值	说明
PORT	3030	监听端口
ARES_HTTP_RATE_LIMIT	60	每个 IP 每分钟的请求数（令牌桶）
ARES_HTTP_MAX_BODY	1000000	请求正文最大字节数
ARES_HTTP_SESSION_TTL_MS	3600000	会话空闲超时时间
ARES_HTTP_ALLOW_ORIGIN	(unset)	如果设置，则作为 Access-Control-Allow-Origin 发送（例如 * 或 https://example.com）

没有内置身份验证——仅将其绑定到 127.0.0.1，或在需要对外开放时在前面部署反向代理。

---

工具

工具	用途
ares_validate_ico	Mod-11 校验和验证。不发起网络调用。
ares_lookup_company	根据 IČO 汇总公司简介。
ares_search_companies	按名称、邮政编码、NACE 和法律形式进行结构化搜索。
ares_get_statutory_bodies	董事、委员会成员、合伙人（来自 VR）。
ares_get_trade_licenses	营业执照（来自 RŽP）。
ares_check_vat_payer	增值税纳税人状态，可选交叉核对 DIČ。
ares_standardize_address	通过 RÚIAN 将自由格式地址规范化为标准地址。
ares_lookup_cz_nace	查询 CZ-NACE 分类。
ares_cross_company_persons	给定 2–50 个 IČO，查找在其中两个或更多企业担任现任法定职务的人员。返回 JSON + Mermaid 图。
ares_search_by_address	查找指定地址上的所有实体，并标记虚拟办公室／空壳地址集中情况。
ares_get_res_classification	来自 RES 的统计分类——规模区间、ESA 2010 部门、NUTS 地区。
ares_check_insolvenci	快速风险提示：该实体是否正在进行破产程序（IR），或被标记为破产（CEÚ）。
ares_full_due_diligence	一站式尽职调查报告——简介 + 法定信息 + 执照 + 增值税 + 破产情况 + 🟢🟡🔴 风险标记 + Markdown 摘要。
ares_export_for_invoicing	将 ARES 简介转换为可供开票系统使用的 Fakturoid / iDoklad / Pohoda 数据载荷。纯转换——不会调用目标系统。

示例提示词

“验证 IČO 27074358，并告诉我它是否为增值税纳税人，以及位于哪个地区。”

“查找在布拉格注册的捷克 IT 公司（CZ-NACE 620）。”

“IČO 26168685 的法定董事有哪些？他们是什么时候获任的？”

“将此地址规范化：‘Za prachárnou 4962/45, Jihlava’。”

“查询软件开发对应的 CZ-NACE 代码。”

“我有以下 IČO：26185610、46967851、46900411、27435148。是否有人在多个企业的董事会任职？请绘制关系图。”

“在我签署任何文件之前，对 IČO 45193258 进行完整的尽职调查。”

尽职调查提示词会调用 ares_full_due_diligence，并返回完整的风险标记报告。真实示例（Liberty Ostrava a.s.，采集于 2026-06-07）：

# Due diligence: Liberty Ostrava a.s.

Risk level: 🔴 RED

Findings:
- 🚨 Active insolvency or bankruptcy on record.

## Identification
- IČO: `45193258`
- DIČ: `CZ45193258` (VAT payer: yes)
- Legal form: 121
- Founded: 1992-01-22
- Registered seat: Vratimovská 689/117, Kunčice, 71900 Ostrava

## Governance
- Active statutary members: 3

## Insolvency
- Insolvenční rejstřík: ACTIVE
- Centrální evidence úpadců: NONE
- Currently insolvent.

对经营状况良好的公司（AGROFERT，IČO 26185610）使用相同提示词，会得到 🟢 GREEN，显示 12 名现任法定成员，且没有发现问题。

最后一个提示词会使用 ares_cross_company_persons。该工具会返回 Mermaid 图，Claude Desktop、Claude Code 和 Cursor 可在行内渲染。在上文的 Agrofert 控股集团示例中，该工具报告 Michal Jedlička 在四个董事会中的三个任职，Jaroslav Kurčík 在其中两个任职——这是控股集团的典型特征。

关于按人员→公司搜索的说明

ARES 的公共 REST v3 API 未提供按人员搜索的端点（AngazovanaOsobaFiltr 架构已定义但未使用）。因此，ares_cross_company_persons 只能针对你提供的已知 IČO 集合运行，不会枚举注册信息。完整的反向查询（“Jan Novák 曾在哪些公司任职？”）需要镜像图数据库，不在这个 MIT 许可服务器的范围内。

---

真实示例——Agrofert 控股公司

使用 Agrofert 集团的四个 IČO（AGROFERT 本身加上三家子公司）运行 ares_cross_company_persons，该工具会返回完整的董事会重叠情况。数据采集自 2026-06-07 的实时 ARES 调用：

zpracovanoIco: 4
totalActivePersons: 29
sharedCount: 3

  • Ing. MICHAL JEDLIČKA (1978-01-06)
       AGROFERT, a.s.            — člen představenstva
       Kostelecké uzeniny a.s.   — předseda představenstva
       Vodňanské kuře, s.r.o.    — Jednatel

  • Ing. JAROSLAV KURČÍK (1969-08-24)
       AGROFERT, a.s.            — člen představenstva
       PENAM, a.s.               — předseda představenstva

  • AGROFERT, a.s. (právnická osoba, IČO 26185610)
       PENAM, a.s.               — člen představenstva
       Kostelecké uzeniny a.s.   — člen představenstva

渲染为 Mermaid 图（Claude Desktop / Claude Code / Cursor 会以内嵌方式渲染）：

graph LR
  C_26185610["AGROFERT, a.s.<br/>26185610"]:::company
  C_46967851["PENAM, a.s.<br/>46967851"]:::company
  C_46900411["Kostelecké uzeniny a.s.<br/>46900411"]:::company
  C_27435148["Vodňanské kuře, s.r.o.<br/>27435148"]:::company
  P_0(["Ing. MICHAL JEDLIČKA"]):::person
  P_0 ---|"člen představenstva"| C_26185610
  P_0 ---|"předseda představenstva"| C_46900411
  P_0 ---|"Jednatel"| C_27435148
  P_1(["Ing. JAROSLAV KURČÍK"]):::person
  P_1 ---|"člen představenstva"| C_26185610
  P_1 ---|"předseda představenstva"| C_46967851
  P_2["AGROFERT, a.s. (IČO 26185610)"]:::legal
  P_2 ---|"člen představenstva"| C_46967851
  P_2 ---|"člen představenstva"| C_46900411
  classDef company fill:#e0f7fa,stroke:#006064,stroke-width:2px;
  classDef person fill:#fff3e0,stroke:#bf360c,stroke-width:2px;
  classDef legal fill:#f3e5f5,stroke:#4a148c,stroke-width:2px;

第三种关联——AGROFERT a.s. 本身被列为两家子公司的法人董事——是一个真实的控股公司模式，逐家公司平铺的列表会遗漏这一点，但图助手会自动呈现。

---

配置

服务器会读取以下可选环境变量：

变量	默认值	说明
ARES_BASE_URL	https://ares.gov.cz/ekonomicke-subjekty-v-be/rest	API 基础 URL
ARES_RATE_PER_SECOND	5	令牌桶请求预算。MFČR 文档规定上限为 500 次请求/分钟（约 8 次请求/秒）；默认值设为 5，以留出余量。不要超过 8。
ARES_TIMEOUT_MS	15000	每次请求的超时时间
ARES_RETRIES	3	可重试错误的重试预算（不包括初始尝试）

---

错误处理

错误会作为 JSON 负载在工具结果中返回（带有 isError: true），以便 Agent 对其进行判断。错误代码：

代码	触发条件
NOT_FOUND	ARES 中不存在该 IČO 或资源。
INVALID_INPUT	输入未通过验证（例如 IČO 校验和错误、缺少搜索筛选条件）。
RATE_LIMITED	ARES 返回 429，且重试次数已用尽。
UPSTREAM_ERROR	ARES 返回 5xx。
NETWORK_ERROR	请求超时或无法发送。

---

数据归属与许可

ARES 数据由捷克财政部作为开放数据发布，采用 Creative Commons Attribution 4.0 (CC BY 4.0) 许可。将这些工具的输出用于你自己的产品、内容或分析时，必须注明来源。

建议使用以下署名文本：

来源：ARES — Administrativní registr ekonomických subjektů，© Ministerstvo financí ČR，https://ares.gov.cz/，采用 CC BY 4.0 许可。

为方便使用，每个工具结果都包含一个 _attribution 字段，其中提供完整的引用信息。

此 MCP 服务的代码采用 MIT 许可证（参见 LICENSE）；上游数据许可证（CC BY 4.0）独立于此代码许可证，且不受其影响。

ARES API 的可接受使用方式

MFČR 发布了 ARES 公共 API 的运行规则。使用此 MCP 服务并不意味着你可以免于遵守这些规则——你的客户端必须遵守这些规则。摘要如下：

• 每位用户每分钟最多 500 次请求。超过此限制，MFČR 保留阻止访问的权利。
• 不要重复发送格式错误的查询。
• 不要维持过多并发自动化查询。
• 不要使用多个 IP 地址规避速率限制。
• 不要随机爬取数据库（例如批量枚举 IČO）。
• 不要探测安全边界。

此服务器强制采用默认每秒 5 次请求（每分钟 300 次）的预算，并使用指数退避。你有责任确保所有实例合计使用量均不超出 MFČR 限制，尤其是在运行多个实例时。

完整运行条件：wwwinfo.mfcr.cz/ares/ares_podminky.html.cz。

免责声明

• 数据为公开信息，不适用于法律程序。 根据 MFČR 的说明，所有来自 ARES 的信息“pouze informativního charakteru”（仅供参考）。如需用于法院程序，请从公共登记处 justice.cz 获取正式摘录。
• ARES 中的增值税纳税人状态最多延迟 24 小时。 权威来源为 MFČR 增值税登记处 adisspr.mfcr.cz。未来的 Premium 层级可能会加入对 MFČR 的直接查询。
• GDPR。 ARES 包含法定代表人的个人数据（姓名、出生日期）。MFČR 基于公共任务这一合法依据（GDPR 第 6(1)(e) 条）发布这些数据。如果你在后续处理中使用这些数据——包括将其传递给你自己的大模型、存储数据或向最终用户展示数据——你就是数据控制者，必须自行遵守 GDPR。本服务默认不会记录请求或存储响应。

---

路线图

• **v0.x（当前）：**8 个免费的 MVP 工具，采用 MIT 许可，通过 npm 分发。
• Premium 层级（计划中）：ares_subscribe_changes、ares_bulk_lookup、ares_due_diligence_report、ares_export_to_invoice_systems。

---

贡献

欢迎提交错误报告和 PR。提交前请运行：

npm run lint
npm run typecheck
npm test

链接

• icovazby.cz — 托管式公司查询
• ARES 门户
• ARES OpenAPI 规范
• ARES Swagger UI
• 模型上下文协议
• MCP TypeScript SDK

许可证

MIT © Miloš Pospíšil