KVK商业数据查询服务

kvk mcp

一个 模型上下文协议 （MCP）服务器 API千伏 （商会）。搜索商业登记处、获取公司简介、查看营业详情和商业名称，所有这些都可以在您的 AI 应用程序中使用自然语言。

让我们来： 这是一个非官方的，由社区维护的项目，不与中小企业有关或批准。

社区建设 模型上下文协议 （MCP）服务器 API千伏 （Kamer van Koophandel/荷兰商会）。搜索Handelsregister，检索公司简介、位置详细信息和商品名——所有这些都可以通过任何兼容MCP的AI客户端通过自然语言完成。

注： 这是一个非官方的、由社区维护的项目，与KVK无关或不受其认可。

快速启动

你不需要克隆这个仓库。

1. 确保安装了 Node.js 20+（您的 AI 应用程序正在运行） npx op-je机器）
2. 获取KVK API密钥（见 API密钥设置)
3. 将服务器添加为 AI 应用程序中的 MCP 服务器（复制下面的配置）
4. 用简单的荷兰语提问（见 例子)

快速入门（非开发人员）

您不需要克隆此仓库。

1. 确保已安装Node.js 20+（您的AI应用程序将运行 npx 在您的机器上）
2. 获取KVK API密钥（请参阅 API密钥设置)
3. 将服务器作为MCP服务器添加到您的AI应用程序中（复制/粘贴下面的配置）
4. 用通俗易懂的语言提问（见 示例用法)

添加到Claude桌面（也适用于协作）

Cowork在Claude Desktop内部运行，并使用相同的连接MCP服务器和权限。

1. 打开您的Claude Desktop MCP配置文件：
   • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
   • 窗户： %APPDATA%\\Claude\\claude_desktop_config.json
2. 添加此服务器条目（或将其合并到现有的 mcpServers):

{
  "mcpServers": {
    "kvk-mcp": {
      "command": "npx",
      "args": ["-y", "kvk-mcp"],
      "env": {
        "KVK_API_KEY": "your-api-key"
      }
    }
  }
}

3. 重新启动克劳德桌面

添加到其他AI应用程序

大多数MCP应用程序都有一个类似“添加MCP服务器”的屏幕，您可以在其中填写：

• 命令： npx
• Args： -y kvk-mcp
• 环境： KVK_API_KEY=your-api-key

如果你的应用程序需要JSON，粘贴它并将顶级键名调整到你的客户端（常见的是 mcpServers, servers，或 context_servers):

{
  "<servers-key>": {
    "kvk-mcp": {
      "command": "npx",
      "args": ["-y", "kvk-mcp"],
      "env": {
        "KVK_API_KEY": "your-api-key"
      }
    }
  }
}

故障排除

• 错误： Missing required env var: KVK_API_KEY
  • 修复：添加 KVK_API_KEY 转到MCP服务器配置并重新启动应用程序。
• 错误： npx: command not found 或服务器无法启动
  • 修复：安装Node.js 20+并重新启动应用程序。
• 您可以连接，但结果为空或您看到 401/403
  • 修复：验证您的KVK API订阅是否与您正在使用的工具匹配（请参阅 每个工具的API订阅).

特性

• 10工具 涵盖KVK Handelsregister和Mutateservice API的3个类别
• 公司搜索 --按名称、KVK号码、RSIN、地址、邮政编码、城市或实体类型查找企业
• 公司基本概况 --注册日期、法律形式、商品名、SBI活动代码、员工人数
• 公司所有者 --RSIN、法律形式（rechtsvorm）、公司所有者的地址和网站
• 主要位置 --地址、商号、网站、SBI活动和hoofdresearch员工
• 所有地点 --列出公司的所有商业和非商业调查
• 位置概况 --分行地址、业务活动、联系方式、商业指标
• 商品名查询 --法定名称、替代商品名和非商业名称
• 突变订阅 --列出活动的Mutateservice订阅
• 突变信号 --浏览和检查受监控公司的变更信号
• 输入验证 通过每个工具上的Zod模式实现安全、可预测的操作
• 响应缓存 具有可配置的TTL（300秒用于搜索，600秒用于配置文件——寄存器数据很少更改）
• 费率限制处理 具有指数回退和 Retry-After 标头支持
• 工具集过滤 仅公开所需的工具类别
• Docker支持 通过GHCR进行集装箱化部署
• 可操作的错误消息 具有上下文感知的恢复建议

支持的客户

{
  "<servers-key>": {
    "kvk-mcp": {
      "command": "npx",
      "args": ["-y", "kvk-mcp"],
      "env": {
        "KVK_API_KEY": "your-api-key"
      }
    }
  }
}

claude mcp add --scope user kvk-mcp \
  --env KVK_API_KEY=your-api-key \
  -- npx -y kvk-mcp

codex mcp add kvk-mcp \
  --env KVK_API_KEY=your-api-key \
  -- npx -y kvk-mcp

gemini mcp add kvk-mcp -- npx -y kvk-mcp

docker run -i --rm \
  -e KVK_API_KEY=your-api-key \
  ghcr.io/bartwaardenburg/kvk-mcp

[mcp_servers.kvk-mcp]
command = "npx"
args = ["-y", "kvk-mcp"]
env = { "KVK_API_KEY" = "your-api-key" }

配置

必需的

从获取API密钥 KVK开发者门户。您需要注册并订阅要使用的API。

可选的

API密钥设置

创建API密钥

1. 在以下网址注册 KVK开发者门户
2. 导航至 API 请求 （请求API）
3. 订阅您需要的API：
   • 搜索 API （搜索）--必填项 search_companies
   • 基本API --需要 get_company_profile, get_company_owner, get_main_location, get_company_locations
   • 企业简介 API --需要 get_location_profile
   • API 命名 --需要 get_trade_names
   • 变异服务API --需要 list_subscriptions, list_signals, get_signal
4. 您的API密钥将在审批后生成

每个工具的API订阅

可用工具

搜索

档案

突变

工具集筛选

通过仅启用所需的工具类别来减少上下文窗口的使用。设置 KVK_TOOLSETS 将环境变量转换为逗号分隔的列表：

KVK_TOOLSETS=search

如果未设置，则启用所有工具集。无效名称将被忽略；如果所有名称都无效，则启用所有工具集作为回退。

密钥标识符

例子

一旦连接，您可以用简单的荷兰语提问：

• “搜索阿姆斯特丹 'Acme' 名称的公司”
• “查找电子邮件编号12345678”
• “显示KVK 69599084的公司简介”
• “这家公司的业务活动（SBI规范）是什么？”
• “输入办公室编号000012345678的办公室详细信息”
• “KVK 12345678使用哪些商标？”
• “查找阿姆斯特丹Herengracht的所有活跃公司”
• “这家公司有多少员工？”
• “谁拥有KVK 12345678？”
• “这家公司的总部在哪里？”
• “显示KVK 12345678的所有分支机构”

示例用法

连接后，您可以使用自然语言与KVK API进行交互：

• “在阿姆斯特丹搜索名为‘Acme’的公司”
• “查找KVK编号12345678”
• “显示KVK 69599084的公司简介”
• “这家公司的业务活动（SBI代码）是什么？”
• “获取查询编号000012345678的位置详细信息”
• “KVK 12345678使用什么商品名？”
• “查找阿姆斯特丹Herengracht上所有活跃的公司”
• “这家公司有多少员工？”
• “KVK 12345678的所有者是谁？”
• “这家公司的主要位置在哪里？”
• “列出KVK 12345678的所有位置”
• “显示我的突变订阅”
• “此订阅有哪些变化？”

社区

• 技术支持： 支持.md
• 安全报告： 安全.md
• 贡献指南： 贡献.md
• Bug报告和功能请求： 问题

发展

# Install dependencies
pnpm install

# Run in development mode
pnpm dev

# Build for production
pnpm build

# Run tests
pnpm test

# Type check
pnpm typecheck

项目结构

src/
  index.ts              # Entry point (stdio transport)
  server.ts             # MCP server setup and toolset filtering
  kvk-client.ts         # KVK API HTTP client with caching and retry
  cache.ts              # TTL-based in-memory response cache
  types.ts              # TypeScript interfaces for KVK API
  tool-result.ts        # Error formatting with recovery suggestions
  update-checker.ts     # NPM update notifications
  tools/
    search.ts           # Company search in the Handelsregister
    profiles.ts         # Company profiles, owner, locations, and trade names
    mutations.ts        # Mutation subscriptions and signals (Mutatieservice)

需求

• Node.js>=20
• A. KVK开发者门户 API订阅帐户

许可证

麻省理工学院-见 许可证 了解详情。