mcp-belgium

npm downloads

One MCP server for Belgian public APIs.

mcp-belgium is the public entry point. It exposes a single aggregated MCP server that bundles Belgian transport, official statistics, open data, addresses, weather, air quality, and geospatial services behind one install and one client config entry.

The package is also prepared for publication to the official MCP Registry under io.github.lacausecrypto/mcp-belgium.

Why use it

• one npm package
• one MCP server entry in your client config
• namespaced tools like irail_*, statbel_*, best_*, kmi_*, urban_*, and urbis_*
• built-in catalog tools, resources, and a prompt so the LLM can discover the right Belgian domain before calling tools
• explicit limitation surfaces when an upstream requires a key or has changed contract

Install

Run directly:

npx -y mcp-belgium

With pnpm:

pnpm dlx mcp-belgium

Global install:

pnpm add -g mcp-belgium
mcp-belgium

Default transport is stdio, which is what desktop MCP clients expect.

Claude Desktop

{
  "mcpServers": {
    "belgium": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-belgium"
      ],
      "env": {
        "LOG_LEVEL": "silent"
      }
    }
  }
}

Optional env vars:

• STIB_API_KEY: enables live STIB/MIVB tools
• CBEAPI_KEY: enables live KBO/BCE company registry tools
• MCP_TRANSPORT=http: runs the server over Streamable HTTP
• PORT_BELGIUM=3017: sets the HTTP port for the aggregated server

What the LLM gets

Alongside the domain tools, mcp-belgium exposes a discovery layer:

• belgium_catalog_overview
• belgium_list_domains
• belgium_describe_domain
• belgium://catalog
• belgium://catalog.json
• belgium://domain/{domain}
• belgium_capability_guide

That means the LLM can:

• inspect the Belgian domains available from this single MCP
• see which domains are live, limited, or key-gated
• understand what kind of data each domain provides
• pick the right namespaced tool without guessing

Main domains

Docs / Wiki

The repo now includes a docs/ tree that works as a lightweight public wiki:

• Docs home
• Installation
• Client configuration
• Domain catalog
• Development
• Release and npm publishing

Local development

Requirements:

• Node.js >= 22
• pnpm >= 9

Setup:

pnpm install
pnpm run build
pnpm run test
pnpm run typecheck

Run the aggregated server over stdio:

pnpm --filter mcp-belgium start:stdio

Run it over Streamable HTTP:

MCP_TRANSPORT=http PORT_BELGIUM=3017 pnpm --filter mcp-belgium start

Run the whole workspace:

docker compose up --build

Monorepo shape

• packages/core: shared HTTP, retry, cache, rate limiting, XML helpers, and MCP response helpers
• packages/mcp-belgium: public aggregated entry point
• packages/mcp-*: domain-specific packages kept modular for maintenance, testing, and isolated validation

The public consumer path is mcp-belgium. Internal workspace packages stay modular for development, but the published mcp-belgium package bundles them so end users install only one npm package.

Upstream caveats

This project wraps public upstream APIs. Some Belgian portals change authentication or endpoint contracts over time. When an upstream is no longer publicly compatible, this project prefers explicit, machine-readable limitation errors over silent failure.

Current examples:

• mcp-stib requires STIB_API_KEY
• mcp-kbo requires CBEAPI_KEY
• mcp-data-gov-be preserves the old tool contract but returns an explicit upstream-changed error
• mcp-opendata-flanders preserves the old tool contract but returns an explicit API-key limitation

Validation

Current workspace checks:

• pnpm run build
• pnpm run test
• pnpm run typecheck
• pnpm audit --prod

License

MIT. See LICENSE.