BORME API

BORME API MCP 连接器

Español：README.es.md

将 Microsoft Copilot、Claude、ChatGPT、Cursor、VS Code 或任何 MCP 客户端连接到托管的 BORME API MCP 服务：西班牙商业登记数据由 BORME（Boletín Oficial del Registro Mercantil）发布，包含自 2009 年以来超过 960 万条事件记录、公司历史、按名称搜索公司、NIF 查询、商标和商业名称，以及风险信号。

该服务托管于 mcp.bormeapi.com；无需安装或运行任何内容，这是推荐的连接方式。本仓库提供相关所需内容：各客户端的连接设置、Agent 技能、事件类型词汇表，以及一个用于封装 BORME API REST 端点的本地 stdio 服务，适用于只能通过 stdio 启动服务的客户端。

持续更新的完整指南位于 bormeapi.com/mcp。如果本 README 与该页面有任何不一致，以该页面为准。

两种连接方式

API 密钥：https://mcp.bormeapi.com/mcp

• 传输方式：Streamable HTTP。每个请求都会收到纯 JSON 响应；调用之间不会保留会话。
• 身份验证：在 X-API-Key 标头中提供你的 API 密钥。未提供密钥时，将应用免费套餐的限制。
• 适用于可发送标头的客户端：Microsoft Copilot Studio、Claude Code、Cursor、VS Code、Claude Desktop（通过 mcp-remote）以及任何其他 Streamable HTTP 客户端。

OAuth：https://mcp.bormeapi.com/mcp/oauth

• 适用于使用 OAuth 登录的自定义连接器助手，例如 Claude.ai、ChatGPT 或 Copilot。无需在任何地方粘贴 API 密钥：使用你的 BORME API 账户登录，应用会使用授权该应用的账户所属套餐。
• 此端点需要 BORME API 账户，并且会忽略 X-API-Key 标头。通过此端点发出的调用会与使用该密钥进行的 REST API 调用和 /mcp 调用共享 API 密钥的每日配额。
• 如果你的账户没有有效的 API 密钥，工具会返回错误并引导你前往账户页面；账户拥有有效密钥后，工具即可恢复使用，无需重新连接应用。
• 如果应用连续 30 天未使用此连接，请重新连接。你可以随时在账户页面的「已连接的应用」下断开应用连接。
• 对于客户端开发者：未经过身份验证的调用会收到 401，并附带 WWW-Authenticate: Bearer resource_metadata="https://mcp.bormeapi.com/.well-known/oauth-protected-resource/mcp/oauth"。 授权服务器为 https://bormeapi.com（元数据位于 /.well-known/oauth-authorization-server），支持动态客户端注册、PKCE（S256）和 mcp 作用域。

在账户页面获取 API 密钥。

设置客户端

Claude.ai（OAuth）

1. 前往「Customize」>「Connectors」>「Add custom connector」。
2. 将 https://mcp.bormeapi.com/mcp/oauth 输入为服务 URL。Claude 会检测登录方式，并显示「Sign in now」和「Register automatically」；请保留这些选项。
3. 点击「Add」。系统会打开我们的登录页面。
4. 使用我们通过电子邮件发送给你的链接登录，然后选择「Allow」。
5. 返回 Claude；如果连接器页面显示该连接器没有工具，请重新加载页面。

在 Team 和 Enterprise 套餐中，所有者需在「Organization settings」下添加连接器。

若要改用 API 密钥，请输入 https://mcp.bormeapi.com/mcp，选择「No sign-in」，然后在「Request headers」下添加 x-api-key 标头并填入你的密钥。Anthropic 仅向有限数量的组织提供测试版请求标头功能；如果你看不到此部分，请使用下方的 Claude Desktop 设置。

ChatGPT（OAuth）

ChatGPT 的自定义连接器无法发送 API 密钥标头。添加自定义连接器，将 https://mcp.bormeapi.com/mcp/oauth 设为服务 URL，然后使用 BORME API 账户登录。界面及其名称可能与 Claude.ai 不同。没有 OAuth 时，ChatGPT 只能在免费套餐下不带密钥使用 https://mcp.bormeapi.com/mcp。

Microsoft Copilot Studio 和 Microsoft 365 Copilot（API 密钥）

以下步骤参考 Microsoft 文档。具体步骤可能因你的租户和数据丢失防护（DLP）策略而异。

1. 在 Copilot Studio 中，打开要使用的 Agent，然后依次选择 Tools > Add a tool > New tool > Model Context Protocol。
2. 输入 Server name（BORME API）、Server description 和 Server URL：https://mcp.bormeapi.com/mcp
3. 在身份验证设置中选择 API key，将 Type 设为 Header，并在标头名称中输入 X-API-Key。选择 Create，然后选择 Create a new connection，输入密钥并选择 Add to agent。
4. 先在 Copilot Studio 中测试 Agent，然后发布并设置 Teams 和 Microsoft 365 Copilot 渠道；具体取决于组织的权限和策略。如果组织设有 Power Platform 数据策略（DLP），管理员可能需要允许此连接器。

Claude Code（API 密钥）

claude mcp add --transport http --scope user \
  --header "X-API-Key: YOUR_KEY" \
  borme https://mcp.bormeapi.com/mcp

--scope user 会使服务在你的所有项目中可用；省略此参数，则只会将其添加到当前项目。

Cursor（API 密钥）

将以下内容添加到 ~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目），并在环境中设置 BORME_API_KEY：

{
  "mcpServers": {
    "borme": {
      "url": "https://mcp.bormeapi.com/mcp",
      "headers": { "X-API-Key": "${env:BORME_API_KEY}" }
    }
  }
}

VS Code（API 密钥）

将以下内容添加到工作区中的 .vscode/mcp.json。服务首次启动时，VS Code 会提示你输入密钥：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "borme-api-key",
      "description": "BORME API key",
      "password": true
    }
  ],
  "servers": {
    "borme": {
      "type": "http",
      "url": "https://mcp.bormeapi.com/mcp",
      "headers": { "X-API-Key": "${input:borme-api-key}" }
    }
  }
}

Claude Desktop（API 密钥）

通过 mcp-remote 将服务添加到 claude_desktop_config.json。这是一个需要 Node.js 的第三方桥接工具：

{
  "mcpServers": {
    "borme": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.bormeapi.com/mcp",
               "--header", "X-API-Key:${BORME_API_KEY}"],
      "env": { "BORME_API_KEY": "YOUR_KEY" }
    }
  }
}

其他 Streamable HTTP 客户端（API 密钥）

将每条 JSON-RPC 消息作为 POST 请求发送到 https://mcp.bormeapi.com/mcp，并设置 Content-Type: application/json、包含 application/json 的 Accept 标头，以及 X-API-Key 中的密钥。例如，列出工具：

curl -s https://mcp.bormeapi.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

本地 stdio 服务

server.py 是一个本地 stdio 服务，用于封装 BORME API REST 端点；推荐使用托管在 mcp.bormeapi.com 上的服务。它提供与托管服务相同的工具，包括名称、标题、描述、参数和注释（所有工具均为只读）；这些内容复制在 tools.json 中。每次工具调用都会向 https://api.bormeapi.com/v1/... 发起一个或多个请求。它不保存数据；MCP 目录会根据其 Dockerfile 构建镜像，以列出这些工具。

• 列出工具无需密钥或网络连接。
• 除 list_act_types 和 registry_stats 外，调用任何工具都需要 API 密钥：与托管 MCP 服务不同，REST API 没有免密免费套餐。你的免费密钥位于账户中。将其设为 BORME_API_KEY。
• daily_digest 和 registry_stats 返回的字段少于托管服务，因为 REST API 没有专用于它们的单个端点：daily_digest 返回当天的事件数量、解析完整度以及最多 200 条破产公告；registry_stats 返回最新发布日期，并在提供密钥时返回最近 30 个发布日期的解析完整度。
• 它不使用 OAuth 登录。

使用 Docker：

docker build -t borme-mcp .
docker run -i --rm -e BORME_API_KEY=YOUR_KEY borme-mcp

使用 Python 3.12：

pip install -r requirements.txt
BORME_API_KEY=YOUR_KEY python server.py

托管服务的工具发生变化时，运行 python scripts/update_tools.py 以重新生成 tools.json，并提交更改。当 tools.json 与托管服务不一致时，CI 会失败。

工具

• search_companies - 按当前名称或曾用名查找公司，并获取排名靠前的公司卡片。
• company_history - 查询一家公司的注册记录时间线：根据你的套餐显示可用的已发布公告，按时间从新到旧排列。
• search_events - 按日期、省份、公告类型和公司名称搜索 BORME 公告。
• daily_digest - 汇总某个发布日的数据，并列出其中的破产公告。
• company_by_nif - 按公司的 NIF/CIF 税号查找公司（Basic 套餐及以上）。
• brand_owner - 查找与某个商标或商号关联的公司（Basic 套餐及以上）。
• company_brands - 查询与某家公司关联的商标和商号（Basic 套餐及以上）。
• recent_signals - 查询最新的风险信号，例如破产申请和大规模退出（Risk 套餐）。
• list_act_types - 查询公告类型及其英文标签和西班牙语原始标题。
• registry_stats - 查询注册数据的规模和覆盖范围。

每个工具的描述和参数架构（由 tools/list 返回）都会说明其参数。

提示词和资源

除工具外，托管服务和本地 stdio 服务还提供提示词和资源。提示词是可直接使用的指令，客户端可向你提供这些指令（在 Claude 中，通过 + 菜单；在其他客户端中，在列出服务提示词的位置查看）；资源则是客户端可以附加为上下文的参考数据。提示词只提供指令：它引导调用的工具仍会照常计入你的套餐用量。

• company_due_diligence（company）：提供一家公司的身份信息、已发布历史、管理人员任命和破产公告报告，并引用每项公告的 BORME id。
• board_changes（company、since）：查询任命、连任、终止任职和辞职、撤销以及依职权取消任命，可选按日期筛选。
• new_companies_digest（province、date）：查询某个省份或自治区在某一天于 BORME 发布注册公告的公司。如果省略 date，则使用最新发布日。
• check_nif（nif）：查询我们的数据中某个 NIF/CIF 关联的公司及其最新已发布公告（Basic 套餐及以上）。

这些提示词会要求模型引用 BORME id，区分名称匹配与已确认的身份或所有权，并且不要将未找到结果视为某事物不存在的证据。

• borme://act-types：公告类型，内容与 list_act_types 返回的一致。
• borme://provinces：省份和自治区列表，省份筛选器接受这些值。该资源需要 BORME_API_KEY；没有密钥时，读取资源会返回获取免费 API 密钥的说明。
• borme://coverage：数据新鲜度，内容与此服务上 registry_stats 返回的一致。

一个资源模板接受公司 slug：

• borme://company/{slug}：按 slug 查询一家公司的最新 20 条已发布事件（例如 borme://company/vaz-metales-sl），返回内容与 company_history 在相同套餐规则下使用 limit 20 和 order desc 时一致。在没有 API 密钥的托管服务上，只能查看过去 7 天内的事件；本地服务需要 BORME_API_KEY。如需查询更多事件，请调用 company_history。

套餐与限制

• **无密钥或免费密钥：**每天 50 次请求，可查询最近 7 天的事件； 按名称搜索公司（前 5 条结果）；查询这 7 天内的公司历史记录和每日 摘要、行为类型列表及注册统计数据。
• **Basic：**每天 5,000 次请求，可查询 365 天的历史记录、NIF；公司搜索结果中 显示 NIF；可查询商标和商号。
• **Pro：**每天 50,000 次请求，可查询自 2009 年以来的完整历史记录。
• **Risk：**每天 200,000 次请求，并可使用风险信号工具。

MCP 服务使用与 REST API 相同的密钥和每日配额。每次工具调用都会计为 密钥（或无密钥时，IP 地址）每日配额中的一次请求。每次调用的结果数量有限 （例如 200 条事件）；工具提供 offset 时，可通过分页查看更多结果。

套餐与价格：bormeapi.com/#pricing。

数据

• 自 2009 年以来，BORME-A 已收录超过 960 万条事件（在 Registro Mercantil 注册的行为），并在每个出版日更新。
• 结果基于已发布的 BORME 公告和其他公开数据。商标或 NIF 关联属于数据匹配， 并不构成法律确认。
• 不包括：年度账目、BORME-C 公告（法律公告）以及 2009 年之前发布的公告。

此仓库中的内容

• skills/borme-registry - 一项 Agent Skill， 用于告知 Agent 应调用哪个工具、如何串联调用，以及如何汇报 答案。 skills/borme-registry-es 是同一项技能的西班牙语版本。请只安装其中一项，不要同时安装两项。对于 Claude Code：

  git clone https://github.com/bormeapi/borme-mcp.git
  mkdir -p ~/.claude/skills && cp -r borme-mcp/skills/borme-registry ~/.claude/skills/
  

  此技能需要连接 MCP 服务。

• vocab/ - 行为类型词汇表：每个枚举都包含其西班牙语 标题和英文标签。

• server.py、prompts.py、 tools.json 和 Dockerfile - 上文所述的本地 stdio 服务，包含其提示词、资源和资源模板； scripts/update_tools.py 会根据托管服务 重新生成 tools.json。

相关内容

• MCP 指南：bormeapi.com/mcp
• REST API 文档：api.bormeapi.com/docs
• Apify actor：西班牙公司注册处 - BORME 事件
• 此仓库：github.com/bormeapi/borme-mcp

许可证

此仓库中的内容遵循 MIT License。

BORME API 提供的数据包含来自 Agencia Estatal Boletín Oficial del Estado（BORME）的公共部门信息，并根据 Law 18/2015 和 RD 1495/2011 重新使用。与 BOE 无关联，也未获其认可。