Kvk Mcp

kvk-mcp

[](https://www.npmjs.com/package/kvk-mcp) [](https://opensource.org/licenses/MIT) [](https://nodejs.org/) [](https://modelcontextprotocol.io) [](https://github.com/bartwaardenburg/kvk-mcp/actions/workflows/ci.yml) [](https://bartwaardenburg.github.io/kvk-mcp/)

Een Model Context Protocol (MCP) server voor de KVK API (Kamer van Koophandel). Doorzoek het Handelsregister, haal bedrijfsprofielen op, bekijk vestigingsgegevens en handelsnamen — allemaal via natuurlijke taal in je AI-app.

> Let op: Dit is een onofficieel, community-onderhouden project en is niet verbonden aan of goedgekeurd door KVK.

A community-built Model Context Protocol (MCP) server for the KVK API (Kamer van Koophandel / Dutch Chamber of Commerce). Search the Handelsregister, retrieve company profiles, location details, and trade names — all through natural language via any MCP-compatible AI client.

> Note: This is an unofficial, community-maintained project and is not affiliated with or endorsed by KVK.

Snel starten

Je hoeft deze repo niet te clonen.

1. Zorg dat Node.js 20+ is geïnstalleerd (je AI-app draait npx op je machine)
2. Haal een KVK API-key op (zie [API Key Setup](#api-key-setup))
3. Voeg de server toe als MCP server in je AI-app (kopieer onderstaande configuratie)
4. Stel vragen in gewoon Nederlands (zie [Voorbeelden](#voorbeelden))

Quick Start (Non-Developers)

You do not need to clone this repo.

1. Make sure Node.js 20+ is installed (your AI app will run npx on your machine)
2. Get a KVK API key (see [API Key Setup](#api-key-setup))
3. Add the server to your AI app as an MCP server (copy/paste config below)
4. Ask questions in plain language (see [Example Usage](#example-usage))

Add To Claude Desktop (Also Works In Cowork)

Cowork runs inside Claude Desktop and uses the same connected MCP servers and permissions.

1. Open your Claude Desktop MCP config file:

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

1. Add this server entry (or merge it into your existing mcpServers):

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

1. Restart Claude Desktop

Add To Other AI Apps

Most MCP apps have a screen like “Add MCP Server” where you can fill in:

• Command: npx
• Args: -y kvk-mcp
• Env: KVK_API_KEY=your-api-key

If your app wants JSON, paste this and adapt the top-level key name to your client (common ones are mcpServers, servers, or context_servers):

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

Troubleshooting

• Error: Missing required env var: KVK_API_KEY
• Fix: add KVK_API_KEY to the MCP server config and restart your app.
• Error: npx: command not found or server fails to start
• Fix: install Node.js 20+ and restart your app.
• You can connect, but results are empty or you see 401/403
• Fix: verify your KVK API subscriptions match the tools you are using (see [API Subscriptions Per Tool](#api-subscriptions-per-tool)).

Features

• 10 tools across 3 categories covering the KVK Handelsregister and Mutatieservice APIs
• Company search — find businesses by name, KVK number, RSIN, address, postal code, city, or entity type
• Basic company profiles — registration date, legal form, trade names, SBI activity codes, employee count
• Company owner — RSIN, legal form (rechtsvorm), addresses, and websites of the company owner
• Main location — address, trade name, websites, SBI activities, and employees of the hoofdvestiging
• All locations — list all commercial and non-commercial vestigingen for a company
• Location profiles — branch addresses, business activities, contact details, commercial indicators
• Trade name lookups — statutory names, alternate trade names, and non-commercial designations
• Mutation subscriptions — list active Mutatieservice subscriptions
• Mutation signals — browse and inspect change signals for monitored companies
• Input validation via Zod schemas on every tool for safe, predictable operations
• Response caching with configurable TTL (300s for search, 600s for profiles — register data changes infrequently)
• Rate limit handling with exponential backoff and Retry-After header support
• Toolset filtering to expose only the tool categories you need
• Docker support for containerized deployments via GHCR
• Actionable error messages with context-aware recovery suggestions

Supported Clients

Advanced setup and supported clients (expand)

This MCP server is not tied to one coding agent. It works with any MCP-compatible client or agent runtime that can start a stdio MCP server.

| Client / runtime | Docs | |---|---| | Claude Code | MCP in Claude Code | | Anthropic API (Messages API) | Remote MCP servers | | Codex CLI (OpenAI) | Codex CLI docs | | Gemini CLI (Google) | Gemini CLI MCP server docs | | VS Code (Copilot) | Use MCP servers in VS Code | | Claude Desktop | MCP in Claude Desktop | | Cursor | Cursor docs | | Windsurf | Windsurf MCP docs | | Cline | Cline MCP docs | | Zed | Zed context servers docs | | Any other MCP host | Use command/args/env from [Generic MCP Server Config](#generic-mcp-server-config) |

Claude Ecosystem Notes

Claude currently has multiple MCP-related concepts that are easy to mix up:

• Local MCP servers (Claude Desktop): defined in claude_desktop_config.json and started on your machine (docs).
• Cowork: reuses the MCP servers connected in Claude Desktop (docs).
• Connectors: remote MCP integrations managed in Claude (docs).
• Cowork plugins: Claude-specific workflow packaging (instructions + tools/data integrations) (docs). Useful in Claude, but not portable as a generic MCP server config for other agent clients.

Verified against vendor docs on 2026-03-05.

Setup (Power Users)

If Quick Start worked in your client, you can skip this section. These are additional per-client setup options and CLI one-liners.

Generic MCP Server Config

Use this in any MCP host that supports stdio servers:

• Command: npx
• Args: ["-y", "kvk-mcp"]
• Required env vars: KVK_API_KEY
• Optional env vars: KVK_CACHE_TTL, KVK_MAX_RETRIES, KVK_TOOLSETS (see [Configuration](#configuration))

Minimal JSON (adapt the top-level key to your host):

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

Host key mapping:

| Host | Top-level key | Notes | |---|---|---| | VS Code | servers | Add "type": "stdio" on the server object | | Claude Desktop / Cursor / Windsurf / Cline | mcpServers | Same command/args/env block | | Zed | context_servers | Same command/args/env block | | Codex CLI (TOML) | mcp_servers | Uses TOML, shown below |

Claude Code

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

Codex CLI (OpenAI)

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

Gemini CLI (Google)

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

Set KVK_API_KEY in ~/.gemini/settings.json.

VS Code (Copilot)

Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P) > MCP: Add Server > Command (stdio), or use .vscode/mcp.json with top-level key servers and the canonical command/args/env block from [Generic MCP Server Config](#generic-mcp-server-config).

Claude Desktop + Cowork / Cursor / Windsurf / Cline / Zed

Cowork runs inside Claude Desktop and uses the same connected MCP servers and permissions. Configure once in Claude Desktop, then the server is available in Cowork.

Use the canonical config block and place it in the host file below with the matching top-level key.

| Client | Config location | Top-level key | |---|---|---| | Claude Desktop (macOS) | ~/Library/Application Support/Claude/claude_desktop_config.json | mcpServers | | Claude Desktop (Windows) | %APPDATA%\\Claude\\claude_desktop_config.json | mcpServers | | Cursor (project) | .cursor/mcp.json | mcpServers | | Cursor (global) | ~/.cursor/mcp.json | mcpServers | | Windsurf | ~/.codeium/windsurf/mcp_config.json | mcpServers | | Cline | MCP settings UI | mcpServers | | Zed (macOS/Linux) | ~/.zed/settings.json or ~/.config/zed/settings.json | context_servers |

Docker

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

Codex CLI (TOML config alternative)

If you prefer editing ~/.codex/config.toml directly:

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

Other MCP Clients

Use the values from [Generic MCP Server Config](#generic-mcp-server-config).

Terminology

What is portable across hosts:

• MCP server runtime settings (command, args, env)
• Transport model (stdio command server)
• Tool names and tool schemas exposed by this server

What is host/vendor-specific (not portable as-is):

• Host config key names (servers, mcpServers, context_servers, mcp_servers)
• Host UX/workflows for adding servers (CLI commands, UI menus, settings paths)
• Anthropic-specific concepts such as Claude Desktop local MCP servers, Claude Connectors via remote MCP, and Claude Code plugins used in Cowork workflows

Security Notes

• Trust model: Any prompt or agent allowed to call this MCP server can execute KVK API actions with the configured credentials.
• Least-privilege credentials: Use separate KVK API keys per environment/team/use case and only required API subscriptions.
• Write-action approvals: Enable host-side approvals for mutating tools (create_subscription and related mutation workflows).
• Team config governance: Keep shared MCP config in version control, require review for changes to command/args/env/toolset filtering, and keep secrets in a vault or host secret manager (not in plain-text repo files).

Configuration

Required

| Variable | Description | |---|---| | KVK_API_KEY | Your KVK API key |

Get your API key from the KVK Developer Portal. You need to register and subscribe to the APIs you want to use.

Optional

| Variable | Description | Default | |---|---|---| | KVK_CACHE_TTL | Enables caching (set to 0 to disable). Tool responses use fixed TTLs (search: 300s, profiles: 600s). | unset | | KVK_MAX_RETRIES | Maximum retry attempts for rate-limited (429) requests with exponential backoff. | 3 | | KVK_TOOLSETS | Comma-separated list of tool categories to enable (see [Toolset Filtering](#toolset-filtering)). | All toolsets |

API Key Setup

Creating Your API Key

1. Register at the KVK Developer Portal
2. Navigate to API's aanvragen (Request APIs)
3. Subscribe to the APIs you need:

• Zoeken API (Search) — required for search_companies
• Basisprofiel API — required for get_company_profile, get_company_owner, get_main_location, get_company_locations
• Vestigingsprofiel API — required for get_location_profile
• Naamgeving API — required for get_trade_names
• Mutatieservice API — required for list_subscriptions, list_signals, get_signal

1. Your API key will be generated after approval

API Subscriptions Per Tool

| API Subscription | Tools | |---|---| | Zoeken (Search) | search_companies | | Basisprofiel (Basic Profile) | get_company_profile, get_company_owner, get_main_location, get_company_locations | | Vestigingsprofiel (Location Profile) | get_location_profile | | Naamgeving (Trade Names) | get_trade_names | | Mutatieservice (Mutation Service) | list_subscriptions, list_signals, get_signal |

Available Tools

Search

| Tool | Description | |---|---| | search_companies | Search the KVK business register by company name, KVK number, RSIN, street, house number, postal code, city, or entity type. Returns up to 100 results per page. |

Profiles

| Tool | Description | |---|---| | get_company_profile | Get the basic company profile (basisprofiel) by KVK number — includes statutory name, trade names, registration dates, SBI activity codes, employee count, legal form, and main branch details | | get_company_owner | Get the owner (eigenaar) of a company by KVK number — includes RSIN, legal form (rechtsvorm), addresses, and websites | | get_main_location | Get the main location (hoofdvestiging) for a company by KVK number — includes address, trade name, websites, SBI activities, and employees | | get_company_locations | List all locations (vestigingen) for a company by KVK number — includes counts and details of commercial and non-commercial locations | | get_location_profile | Get a location profile (vestigingsprofiel) by vestigingsnummer — includes full address, business activities, employee breakdown, website, and commercial indicators | | get_trade_names | Get all trade names (handelsnamen) for a KVK number — includes statutory name, commercial and non-commercial designations per branch |

Mutations

| Tool | Description | |---|---| | list_subscriptions | List all mutation subscriptions (abonnementen) for the KVK Mutatieservice — returns active subscriptions with IDs and descriptions | | list_signals | List mutation signals (signalen) for a specific subscription — returns a paged list of change signals with filtering by date range | | get_signal | Get the full details of a specific mutation signal by subscription ID and signal ID |

Toolset Filtering

Reduce context window usage by enabling only the tool categories you need. Set the KVK_TOOLSETS environment variable to a comma-separated list:

KVK_TOOLSETS=search

| Toolset | Tools included | |---|---| | search | Company search in the Handelsregister | | profiles | Basic profiles, owner, main location, all locations, location profiles, and trade names | | mutations | Mutation subscriptions, signals, and signal details (Mutatieservice) |

When not set, all toolsets are enabled. Invalid names are ignored; if all names are invalid, all toolsets are enabled as a fallback.

Key Identifiers

| Identifier | Format | Description | |---|---|---| | KVK nummer | 8 digits (e.g. 12345678) | Unique company registration number | | Vestigingsnummer | 12 digits (e.g. 000012345678) | Unique b

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: BartWaardenburg
• Source: BartWaardenburg/kvk-mcp
• License: MIT
• Homepage: https://github.com/BartWaardenburg/kvk-mcp#readme

Install and usage instructions live in the source repository linked above.