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)
3. Voeg de server toe als MCP server in je AI-app (kopieer onderstaande configuratie)
4. Stel vragen in gewoon Nederlands (zie 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)
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)

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
2. 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"
      }
    }
  }
}

3. 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):

{
  "<servers-key>": {
    "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).

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

{
  "<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" }

Configuration

Required

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

Optional

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
4. Your API key will be generated after approval

API Subscriptions Per Tool

Available Tools

Search

Profiles

Mutations

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

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

Voorbeelden

Eenmaal verbonden kun je in gewoon Nederlands vragen stellen:

• "Zoek bedrijven met de naam 'Acme' in Amsterdam"
• "Zoek KVK-nummer 12345678 op"
• "Toon het bedrijfsprofiel voor KVK 69599084"
• "Wat zijn de bedrijfsactiviteiten (SBI-codes) van dit bedrijf?"
• "Geef de vestigingsgegevens voor vestigingsnummer 000012345678"
• "Welke handelsnamen gebruikt KVK 12345678?"
• "Vind alle actieve bedrijven op de Herengracht in Amsterdam"
• "Hoeveel werknemers heeft dit bedrijf?"
• "Wie is de eigenaar van KVK 12345678?"
• "Wat is de hoofdvestiging van dit bedrijf?"
• "Toon alle vestigingen voor KVK 12345678"

Example Usage

Once connected, you can interact with the KVK API using natural language:

• "Search for companies named 'Acme' in Amsterdam"
• "Look up KVK number 12345678"
• "Show me the company profile for KVK 69599084"
• "What are the business activities (SBI codes) for this company?"
• "Get the location details for vestigingsnummer 000012345678"
• "What trade names does KVK 12345678 use?"
• "Find all active companies on Herengracht in Amsterdam"
• "How many employees does this company have?"
• "Who is the owner of KVK 12345678?"
• "What is the main location for this company?"
• "List all locations for KVK 12345678"
• "Show my mutation subscriptions"
• "What changes have been signalled for this subscription?"

Community

• Support: SUPPORT.md
• Security reporting: SECURITY.md
• Contributing guidelines: CONTRIBUTING.md
• Bug reports and feature requests: Issues

Development

# Install dependencies
pnpm install

# Run in development mode
pnpm dev

# Build for production
pnpm build

# Run tests
pnpm test

# Type check
pnpm typecheck

Project Structure

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)

Requirements

• Node.js >= 20
• A KVK Developer Portal account with API subscription

License

MIT - see LICENSE for details.