mcp-borme

MCP BORME

一款用于 BORME（Boletín Oficial del Registro Mercantil，西班牙商业登记公报）的 Model Context Protocol（MCP）服务，基于公共的 OpenMercantil API 构建。它可以让 Claude 等 AI 助手搜索西班牙公司、查看公司登记历史和高管信息、浏览每日公报、按 CNAE 对行业进行分类、查看公共采购信息，以及查询各项登记行为背后的商法规范。

由 Nubiia 构建并维护 — 为企业提供自动化与 AI 集成服务（MCP、Holded、Pipedrive 等）。想为你的企业打造类似方案？请访问 nubiia.es 联系我们。

独立且仅供参考。 OpenMercantil 并非 BOE、BORME 或 Registro Mercantil，其数据不能替代官方证明或登记摘录。BORME 内容依据 Ley 37/2007 重新使用；官方版本请见 boe.es。工具响应会保留来源归属信息（_attributions），工具描述也会重复说明相关文档仅供参考且不构成法律建议。

无需账户

OpenMercantil API 是公开的：本服务开箱即用，可使用匿名免费套餐（每个 IP 每分钟 60 次请求，每天 200 次请求）。可选的 API 密钥（OPENMERCANTIL_API_KEY，omk_...，从 openmercantil.es 获取）可使用你账户的更高额度：

套餐	每分钟	每天
Free（匿名，按 IP 计）	60	200
Profesional（API 密钥）	120	5,000
MAX（API 密钥）	600	50,000
Enterprise（合同）	1,200	500,000+

套餐可能会变更 — 请查看 openmercantil.es 和 docs/api-notes.md。每天 200 次请求，本服务力求节省额度：

• 每项输入都会根据 OpenAPI 限制在本地进行验证，因此错误调用不会消耗请求额度。
• 结果数量默认设置较小（10 条结果、10 个事件、每个省份 10 项公告），大型响应会经过精简并附上明确提示（events_total、events_truncated、total_acts 等），让助手了解哪些内容未能查看，以及应使用哪些工具分页获取剩余内容。完整公司报告（约 60 KB）会精简为约 6 KB；完整的一日公报（约 340 KB）则会汇总为按省份分类的信息。
• 任何超过 OPENMERCANTIL_MAX_RESPONSE_CHARS（默认值为 60,000）的响应，都会替换为有效的 JSON 封装，并说明内容已被截断。
• 响应会包含 API 的速率限制状态；遇到 429 时会说明套餐、可重试时间以及如何提升额度。较短的 Retry-After 值会自动遵循；较长的等待时间（每日额度限制）则会立即告知，而不会阻塞请求。

功能

37 个只读工具，均标记为 readOnlyHint: true——此服务不会向 OpenMercantil 或其他任何地方写入数据。

• 公司（11）：borme_search_companies、borme_get_company、 borme_compare_companies、borme_get_company_events、borme_get_company_facts、 borme_get_company_timeline、borme_get_company_officers、 borme_get_company_relationships、borme_get_company_graph、 borme_get_company_activity、borme_get_similar_companies
• 各公司的其他公开来源（7）：borme_get_company_contracts、 borme_get_company_grants、borme_get_company_ted、borme_get_company_cnmv、 borme_get_company_wikidata、borme_get_company_bde、borme_get_company_sources
• 每日公告（1）：borme_get_daily_summary
• 人员（3）：borme_search_persons、borme_get_person、borme_get_person_graph
• 行业／CNAE（4）：borme_list_sector_companies、borme_get_sector_ratios、 borme_get_cnae、borme_get_cnae_tree
• 商法（4）：borme_list_legal_norms、borme_get_legal_norm、 borme_get_legal_article、borme_get_act_map
• 公共采购（4）：borme_search_tenders、borme_get_tender、 borme_get_tender_stats、borme_list_tender_suppliers
• 服务（3）：borme_get_health、borme_get_stats、borme_get_sources_freshness

有意排除的范围

所有不属于 OpenMercantil 公开只读层的内容：用户账户、列表、备注、分组、API 凭证和 webhook 管理、账单、支持工单以及法律报告购买流程（这些操作都会写入数据或需要浏览器会话）。此外还排除了：批量 export/* 和 CSV 下载、旧版别名、汇总仪表板（ccaa/stats、sectores/stats、datasets/public、integrations），以及各公司的风险信号端点（制裁、扣押、AEAT 欠税人、评分）；这些端点不在公共 API 的允许凭证范围内。

安装

前置条件

• Node.js 22.14 或更高版本
• 可选：从 openmercantil.es 获取 OpenMercantil API 密钥

从 npm 安装

npm install -g @nubiia/mcp-borme

从源代码安装

git clone https://github.com/nubiia-dev/mcp-borme.git
cd mcp-borme
npm install
npm run build

配置

环境变量

变量	必需	说明
OPENMERCANTIL_API_KEY	否	OpenMercantil API 密钥（omk_...）。属于机密信息，切勿提交。未设置时将使用匿名免费层。密钥通过 X-API-Key 请求头发送，绝不会放在 URL 中，并且会从错误消息中删去。
OPENMERCANTIL_MAX_REQUESTS_PER_MINUTE	否	所有工具每分钟请求数的本地上限。默认值为 60（匿名用户的限制）；可通过付费方案提高。
OPENMERCANTIL_MAX_RESPONSE_CHARS	否	单个工具响应的最大长度。默认值为 60000；超出长度的结果会被截断并附带提示。
OPENMERCANTIL_BASE_URL	否	覆盖 API 主机（镜像、本地模拟）。仅支持 https，但 http://localhost 除外。

export OPENMERCANTIL_API_KEY=omk_your_key   # optional

Claude Desktop 配置

将以下内容添加到 Claude Desktop 配置文件：

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

{
  "mcpServers": {
    "borme": {
      "command": "npx",
      "args": ["-y", "@nubiia/mcp-borme@latest"],
      "env": {
        "OPENMERCANTIL_API_KEY": "omk_your_key"
      }
    }
  }
}

若不使用密钥，请完全移除 env 块。若从源代码安装：

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

Claude Code 配置

# anonymous free tier
claude mcp add borme -- npx -y @nubiia/mcp-borme@latest

# with an API key
claude mcp add borme --env OPENMERCANTIL_API_KEY=omk_your_key -- npx -y @nubiia/mcp-borme@latest

故障排查

• 在此仓库内启动时出现 sh: mcp-borme: command not found。 如果你从克隆后的仓库目录启动 Claude Code（或其他 MCP 客户端），npx @nubiia/mcp-borme 会解析本地 package.json，而 mcp-borme 二进制文件不在 PATH 中。使用 @latest 固定到注册表版本（如上方示例所示），或从其他目录启动客户端。
• 似乎缺少近期日期或公司。 OpenMercantil 数据集会定期重建，可能落后于官方公报。调用 borme_get_health，查看 latest_borme_processed 和 status，了解数据的新鲜度。
• 补助金 / TED / CNMV / Wikidata / 来源出现 503 projection_unavailable。 这些工具会读取 OpenMercantil 可能下线的集成投影数据；这是服务端状态，并不代表该公司没有此类记录。

工具

推荐的工作流：borme_search_companies → borme_get_company → 详情工具。 公司工具使用搜索返回的 slug（例如 telefonica-de-espana-sa）。

borme_search_companies · 只读

按名称前缀、别名或精确 CIF 搜索。返回 slug、CIF、省份、CNAE、股本（分）、首次 / 最近一次出现在 BORME 的记录，以及行为数量。DNI / NIE 不会匹配。

{ "q": "Telefónica de España", "limit": 5 }

borme_get_company · 只读

完整的 BORME 报告：身份信息、关键指标、活动时间线、主要事件类型、最近事件（events_limit，默认值为 10；响应中会报告 events_total）以及现任和历任负责人。使用 borme_get_company_events 分页查看完整历史记录。

borme_get_company_events · 只读

某公司的某一日历年 BORME 行为（year，默认值为当前年份），支持分页（page、page_size ≤ 100）。请查看 total 和 pages。

{ "slug": "telefonica-de-espana-sa", "year": 2025, "page_size": 20 }

borme_get_company_facts、borme_get_company_timeline、borme_get_company_officers、borme_get_company_relationships、borme_get_company_graph、borme_get_company_activity、borme_get_similar_companies、borme_compare_companies

按行为类型整理的结构化事实、统一的注册登记与采购时间线、负责人、文献记载的关系（可按 type / confidence 筛选）、集团关系图、月度活动序列、同省份且 CNAE 类别相同的同业公司，以及两家公司对比。所有数据均以文献记录为依据：被提及不代表当前状态已获证实。

borme_get_company_contracts、_grants、_ted、_cnmv、_wikidata、_bde、_sources

公共采购（PLACSP）、补贴（BDNS）、欧盟招标（TED）、上市信息（CNMV）、Wikidata 标识符、西班牙银行行业比率，以及这些来源的覆盖范围图。结果为空不代表相关信息不存在。

borme_get_daily_summary · 只读

按章节和省份查看 BORME 在某个日期发布的内容。由于一天可能包含数千条行为，响应会给出精确数量，以及每个省份最前面的 limit 条行为（默认值为 10）。可按 province / section（"1" 为登记行为，"2" 为公告）缩小范围。周日和节假日不发布公报（404）。

{ "date": "2026-07-07", "province": "Madrid", "limit": 20 }

borme_search_persons、borme_get_person、borme_get_person_graph

人员信息仅以文献中的姓名提及形式出现（通常为负责人）。同名者共用一个 slug，系统不会解析身份，也不会公开 DNI、地址或联系信息。

borme_list_sector_companies、borme_get_sector_ratios、borme_get_cnae、borme_get_cnae_tree

CNAE 行业的公司（可选按省份筛选）、西班牙银行按两位数类别汇总的比率、代码元数据及代码层级。

borme_list_legal_norms、borme_get_legal_norm、borme_get_legal_article、borme_get_act_map

整合后的商法规范（BOE 文本），以及每种 BORME 行为类型与其适用法律之间的对应关系。仅供参考，不构成法律建议。

borme_search_tenders、borme_get_tender、borme_get_tender_stats、borme_list_tender_suppliers

公共采购公告，支持按 CPV / 阶段 / 省份 / 买方 / 供应商 / 金额 / 日期筛选，并支持游标分页。API 会拒绝某些筛选条件组合（自由文本与结构化筛选条件同时使用，或将 cpv 与日期以外的条件组合），并原样返回 422 错误。

borme_get_health、borme_get_stats、borme_get_sources_freshness

数据集大小和新鲜度——在断言某项内容“尚未发布”前，值得先检查。

速率限制

本地保护机制会在 Agent 循环失控、耗尽每日配额前将其拦截：

范围	限制
所有工具合计	OPENMERCANTIL_MAX_REQUESTS_PER_MINUTE（默认 60 次/分钟）
每个工具	30 次/分钟

429/502/503/504 响应以及连接被拒绝/DNS 错误会在退避后重试（3 次）；为避免浪费配额，超时和连接重置不会重试。每次尝试的超时时间为 30 秒。

错误消息

错误会说明应采取的操作：429 会包含套餐、重试时间和匿名用户的限制；401/403 会提示检查 OPENMERCANTIL_API_KEY；针对公司或个人的 404 会说明 OpenMercantil 从不确认被隐去的信息或个人身份。所有错误消息都会隐藏 API 密钥。

开发

npm install
npm run build
npm test              # runs entirely against mocks — no network, no API key
npm run test:coverage
npm run lint
node scripts/smoke.mjs   # live smoke test against the real API (about 10 requests)

完整工作流请参阅 CONTRIBUTING.md，经实时服务验证的 API 行为请参阅 docs/api-notes.md。

许可证

MIT。OpenMercantil 提供的数据受每个响应中以及 openmercantil.es/terminos-de-uso 上公布的特定来源条款约束。

相关项目

• @nubiia/mcp-newsapi ——用于 NewsAPI.ai（Event Registry）新闻 API 的 MCP 服务。
• @nubiia/mcp-holded ——用于 Holded 发票/会计 API 的 MCP 服务。
• @nubiia/mcp-signaturit ——用于 Signaturit 电子签名 API 的 MCP 服务。