kvk-connect 1.7.1

Client + domain mapping for KVK API

KvK-connect

Inhoudsopgave

1. Introductie
2. Vereisten
3. Snel aan de slag
   • Als bibliotheekgebruiker
   • Met Docker
   • Als ontwikkelaar
4. Structuur van KvK
5. Data Flow
6. MCP Server
7. Database Schema
8. Functionaliteit
9. Ontwikkelaarsgids
10. Roadmap
11. KvK API Documentatie

---

Introductie

De Kamer van Koophandel (KvK) biedt meerdere APIs die samen informatie verstrekken over bedrijven. Uitvoerige documentatie is hier te vinden: https://developers.kvk.nl/documentation

Veel overheidsinstanties hebben een wettelijke taak voor vergunningsverlening, toezicht en handhaving (VTH) en gebruiken deze informatie voor validatie en opslag in hun systemen. Het controleren bij aanvraag gaat vaak met eenmalige KvK-bevragingen, maar signalen dat bedrijven hun statuten wijzigen of ophouden te bestaan zijn ook relevant.

Voor met name de laatste categorie is er synergie te behalen door het eenduidig opzetten van bevragingen en volgen van bedrijfsmutaties. Dit project maakt het bevragen-, opslaan- en werken met deze informatie eenvoudig, eenduidig en deelbaar. Het idee is dat elke instantie met een eigen KvK subscription op hun eigen infrastructuur in korte tijd een eenvoudig werkende en compliant omgeving heeft opgezet waar direct mee gewerkt kan worden.

---

Vereisten

[NB] Dit project vereist een KVK API key om te functioneren. Verkrijg een key via KvK Portaal. Voor het volgen van mutaties is een additioneel abonnement nodig.

---

Snel aan de slag

Als bibliotheekgebruiker

Installeer het pakket en start direct met KvK-gegevens opvragen:

pip install kvk-connect

from kvk_connect import KVKApiClient, KVKRecordService

client = KVKApiClient(api_key="your_kvk_api_key")
service = KVKRecordService(client)
basisprofiel = service.get_basisprofiel("12345678")

NB: De package naam is kvk-connect, maar imports werken met kvk_connect (underscore) in Python.

Met Docker (productie)

Voor omgevingen die op basis van pre-built images uit GHCR willen deployen, zoals Portainer icm Watchtower, is er een docker-compose file. Lokaal bouwen is dan niet nodig.

cp .env.docker.example .env.docker
# Bewerk .env.docker met KVK API-sleutel, SQL-connectiestring en KVK_VERSION

# Start services (haalt images op van ghcr.io/minbzk/)
docker compose -f docker-compose.prod.yaml up -d

De images bevatten Watchtower-labels, zodat een draaiende Watchtower-instantie updates automatisch oppakt. Hierbij wordt gemonitord op de laatste 'latest' image, als deze afwijkt wordt deze automatisch gedeployed en de services restart.

Met Docker (stand-alone)

Start een stand-alone lokale instantie met docker compose:

# Clone en configureer
git clone https://github.com/MinBZK/kvk-connect.git
cd kvk-connect

# Environment instellen
cp .env.docker.example .env.docker
# Bewerk .env.docker met je KvK API-sleutel en alle POSTGRES_* settings, PostgreSQL zal met deze waarden initieren.

# Start services (PostgreSQL + alle apps)
docker compose -f docker-compose.local.yaml up -d

# Check logging met
docker compose logs -f .

Op poort 5432 draait nu een PostgreSQL instantie met een kvkconnect db zoals uitgelegd onder Database Schema, deze wordt actueel gehouden door de container-apps, zie Data Flow.

Met Docker (externe Database)

Idem als hierboven, maar gebruik nu de docker-compose.db.yaml file en zet andere variabelen.

cp .env.docker.example .env.docker
# Bewerk .env.docker met je KvK API-sleutel en SQL Connectie string naar externe DB.

# Start services
docker compose -f docker-compose.db.yaml up -d

Voor externe databases moet de database, gebruikersnaam en rechten eerst aangemaakt worden alvorens verbinding gemaakt kan worden.

Als ontwikkelaar

Clone het project, installeer afhankelijkheden en voer de volledige development workflow uit:

git clone https://github.com/MinBZK/kvk-connect.git
cd kvk-connect

just install      # Bibliotheek + dev tools installeren
just check-all    # Alle checks uitvoeren (lint, type, tests)
just test         # Tests met coverage
just bump patch   # Versie bumpen
just tag v0.1.5   # Release-tag maken

Alle build, lifecycle, run en development-taken zijn als recipes gedefinieerd in Justfile als single source of truth. Installeer just en draai just zodat je alle gedefinieerde recipes te zien krijgt:

$ just
Available recipes:
    [deployment]
    build                            # build the distribution packages
    bump tag                         # bump the version in pyproject.toml use: patch, minor, or major
    deploy version                   # publish the package to PyPI
    tag tag msg                      # create and push a git tag use: tag name and message

    [docker]
    docker-build env='local'         # Docker compose up ('local' by default, use 'db' external db build)
    docker-down env='local'          # Docker compose down
    docker-logs env='local' *service # View logs from Docker services
    docker-restart env='local'       # Restart Docker services
    docker-up env='local'

    [lifecycle]
    install                          # First install
    update                           # Update dependencies

    [qa]
    check-all                        # Perform all checks [alias: a]
    cov                              # Run tests and measure coverage
    lint                             # Run linters
    pc                               # Check pre-commit hooks
    test *args                       # Run tests [alias: t]
    typing                           # Check types

---

Structuur KvK

• Basisprofiel: Algemene informatie over een bedrijf, zoals naam, KVK nummer, RSIN, oprichtingsdatum, rechtsvorm, eigenaar, etc.

  • Uniek kenmerk: kvk_nummer

• Basisprofiel_historie: Elke wijziging over tijd aan een basisprofiel

  • Uniek kenmerk: kvk_nummer

• Vestigingen: Elke kvkNummer heeft 0 of meer vestigingen.

  • Uniek kenmerk: kvk_nummer met vestigingsnummmer of '0000000' als er geen vestiging bestaat.

• Vestigingen_historie: Elke wijziging aan een vestiging van een basisprofiel

• Vestigingsprofiel: Informatie over een specifieke vestiging van een bedrijf, zoals post- en bezoek-adres en locatie

  • Uniek kenmerk: vestiging_nummer

• Vestigingsprofiel_historie: Elke wijziging aan een vestigingsprofiel over tijd.

• Signalen: KvK lijst van mutatie-signalen. Hiermee wordt informatie gegeven welk kvknummer een mutatie heeft verwerkt. De Signaal informatie zelf wordt vooralsnog niet verwerkt. Deze mutaties zijn input voor de 4 apps om nieuwe informatie op te halen.

  • NB: Voor deze mutaties is een losse subscription nodig bij de KvK.

--

Data Flow van de Docker Apps

De vijf Docker apps werken onafhankelijk van elkaar samen om de KVK data actueel te houden:

MCP Server

De MCP server (apps/mcp-server/) stelt de KVK datamirror beschikbaar voor LLMs via het Model Context Protocol. Hiermee kan een LLM zelfstandig bedrijfsgegevens opzoeken, vestigingen doorzoeken en mutaties analyseren.

Tools

Laag	Tool	Omschrijving
Exacte lookups	get_bedrijf	Basisprofiel voor KVK-nummer
	get_vestiging	Vestigingsprofiel voor vestigingsnummer
	list_vestigingen	Alle vestigingen van een KVK-nummer
	get_alles	Basisprofiel + alle vestigingen in één aanroep
	check_doorstarter	Zoek actieve opvolger op hetzelfde adres
Analytisch	zoek_op_naam_prefix	Zoek bedrijven op naam
	filter_op_sbi	Filter vestigingen op SBI-sector en gemeente
	check_actiefstatus_batch	Actiefstatus voor meerdere KVK-nummers
Historie	get_basisprofiel_historie	Wijzigingsgeschiedenis basisprofiel
	get_vestigingsprofiel_historie	Wijzigingsgeschiedenis vestigingsprofiel
Overig	report_onbekende_vraag	Registreert vragen die niet beantwoord kunnen worden

Starten

De MCP server draait automatisch mee met Docker Compose op poort 8001:

docker compose -f docker-compose.local.yaml up -d
curl http://localhost:8001/health  # {"status": "ok"}

Transport

Het transport is configureerbaar via de MCP_TRANSPORT environment variable:

Waarde	Gebruik
streamable-http	Default. Voor Docker en HTTP-clients (lokale LLMs)
stdio	Voor directe integratie met Claude Desktop
sse	Legacy, vervangen door streamable-http

Verbinden met Claude Desktop

De MCP server draait als HTTP-service. Claude Desktop heeft de mcp-remote bridge nodig om via stdio met een HTTP-endpoint te communiceren.

npm install -g mcp-remote

Voeg toe aan claude_desktop_config.json (Settings > Developer > Edit Config):

{
  "mcpServers": {
    "kvk-connect": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": [
        "<pad-naar-npm-global>/node_modules/mcp-remote/dist/proxy.js",
        "http://localhost:8001/mcp"
      ]
    }
  }
}

Zoek het globale npm pad met npm root -g. Herstart Claude Desktop na het aanpassen van de config.

---

Database Schema (ORM Model)

Functionaliteit

• Rate-Limiting
  • We volgen de door KvK gestelde limiet op API calls. Zowel in de kvk-connect library en in docker-compse via een rate limiting gateway.
  • Exponential back-off bij tijdelijke downtime of overschreiden van de rate-limit
• Command Line Interface:
  • Handmatig ophalen van eenmalige informatie.
  • Seeden van de basis profielen middels een CSV file.
• Automatisch volgen van mutatiesignalen middels pull requests.
• Database agnotisch
  • SQLAlchemy ondersteund een lange lijst van DB implementaties: Zie https://docs.sqlalchemy.org/en/21/dialects/index.html. Getest met SQLLite, MS SQL en PostgreSQL
  • We hebben twee docker-compose scripts:
    • 'local': Volledig self contained containers met PostgreSQL
    • 'ext': Zelfde functionaliteit, maar met connectie naar externe database.
• Databases met tabellen worden automatisch aangemaakt, indexen en constraints worden toegevoegd voor optimale werking.
• Wijzigingshistorie per veld
  • Bij elke sync worden gewijzigde velden vastgelegd in aparte historietabellen (basisprofielen_historie, vestigingsprofielen_historie, vestigingen_historie).
  • Identieke re-fetches genereren geen nieuwe rij. Verwijderde vestigingen worden als afzonderlijk 'verwijderd'-event opgeslagen.

Roadmap

• HelmChart voor deploy
• PowerBI rapport welke aangesloten kan worden en direct kan werken met de opgehaalde data.