cbs-statistics-mcp-server by TCLUBNL - MCP Server

📊 CBS Statistics MCP Server

Unified data gateway for CBS Open Data APIs (demographics, economics, labor, etc.)

This project implements an MCP (Model Context Protocol) server providing structured access to statistical and demographic data from the Centraal Bureau voor de Statistiek (CBS) of the Netherlands.

🧠 Architecture Overview

Client: Statistics & Demographics MCP Client

Lives inside an MCP host (e.g., Claude Desktop)
Uses the defined manifest (mcp.json) to understand available tools, resources, and prompts
Sends user queries to the CBS MCP Server for structured data retrieval and analysis

Server: CBS Statistics MCP Server (this project)

Built using Python (FastAPI)
Provides unified access to multiple CBS Open Data APIs through REST endpoints
Contains tools (API logic), resources (API definitions), and prompts (analysis templates)
Exposes mcp.json for automatic client integration

🌍 APIs Included

API	Description	Example Use
CBS Open Data	Core API providing structured access to CBS datasets	General data access layer for all submodules
Wijken en Buurten	Neighborhood-level statistics on demographics, population, housing	Analyze potential store locations or population density by postal code
Bevolkingsstatistieken	National and regional population data (size, growth, migration)	Understand population trends for market expansion
Economische Indicatoren	Economic performance data (income, consumption, GDP per region)	Assess purchasing power or economic strength of a region
Arbeidsmarkt	Labor market indicators (employment rate, sectoral distribution)	Evaluate workforce availability and regional employment stability

🚀 Quick Start

1. Clone the Repository

git clone https://github.com/TCLUBNL/cbs-statistics-mcp-server.git
cd cbs-statistics-mcp-server

2. Create Virtual Environment

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install Dependencies

pip install -r requirements.txt

4. Run the Server

uvicorn server.main:app --reload --port 4001

The server will start at http://localhost:4001

5. Test the API

curl http://localhost:4001/

🔌 Connect to Claude Desktop

Open Claude Desktop settings
Navigate to Model Context Protocol → Add Server
Enter server URL: http://localhost:4001/mcp.json
Save and restart Claude Desktop

Claude will automatically load all CBS Statistics tools, resources, and prompts.

📡 API Endpoints

Endpoint	Description
`GET /`	Server status and endpoint list
`GET /mcp.json`	MCP manifest for client integration
`GET /api/neighborhood/{code}`	Fetch neighborhood statistics by CBS code
`GET /api/population?region={name}`	Get population data (national or regional)
`GET /api/economy?region={name}`	Get economic indicators
`GET /api/labor?region={name}`	Get labor market data
`GET /api/search?query={keyword}`	Search CBS datasets by keyword

💼 Business Use Cases

Retail Expansion

A retail chain can identify optimal store locations by:

Retrieving demographic and economic data per neighborhood
Filtering areas with high population density and income levels
Cross-referencing employment rates and economic growth
Generating human-readable insights via MCP prompts

Urban Planning

Government agencies can use the data for:

Population trend analysis
Infrastructure planning based on demographic shifts
Economic development zone identification

Market Research

Businesses can leverage the data for:

Target market identification
Competitive analysis by region
Consumer purchasing power assessment

🏗️ Project Structure

cbs-statistics-mcp-server/
│
├── mcp.json                           # MCP manifest (root of the system)
│
├── server/
│   ├── main.py                        # FastAPI entry point
│   │
│   ├── tools/                         # Individual logic modules (Python)
│   │   ├── get_neighborhood_stats.py
│   │   ├── get_population_data.py
│   │   ├── get_economic_indicators.py
│   │   ├── get_labor_market_data.py
│   │   └── search_cbs_datasets.py
│   │
│   ├── resources/                     # YAML definitions for each CBS dataset
│   │   ├── cbs_open_data.yaml
│   │   ├── wijken_buurten.yaml
│   │   ├── bevolkingsstatistieken.yaml
│   │   ├── economische_indicatoren.yaml
│   │   └── arbeidsmarkt.yaml
│   │
│   ├── prompts/                       # Prompt templates for MCP client
│   │   ├── analyze_neighborhood_potential.md
│   │   ├── find_optimal_store_location.md
│   │   ├── demographic_summary.md
│   │   └── compare_economic_zones.md
│   │
│   └── utils/                         # Optional helper functions
│
├── requirements.txt                   # Python dependencies
├── .gitignore                         # Git ignore rules
└── README.md                          # This file

🧠 Example MCP Workflow

Claude Desktop (client) connects to http://localhost:4001/mcp.json
Claude loads all available tools, resources, and prompts
User asks:

"Find promising neighborhoods near Utrecht for a new store."
MCP server:
- Queries Wijken en Buurten and Economische Indicatoren datasets
- Applies the find_optimal_store_location.md prompt logic
- Returns data-rich insights with tables and summaries

🪄 Technology Stack

FastAPI - Modern Python web framework for APIs
Requests - HTTP library for CBS API calls
Pandas - Data manipulation (optional enhancement)
PyYAML - YAML configuration parsing
Uvicorn - ASGI server for FastAPI

📚 CBS Data Sources

All data comes from CBS Open Data Portal:

🔗 CBS Open Data StatLine
🔗 CBS OData API Documentation

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License.

🔗 Links

Repository: https://github.com/TCLUBNL/cbs-statistics-mcp-server
CBS Open Data: https://opendata.cbs.nl
MCP Protocol: https://modelcontextprotocol.io

Built with ❤️ for data-driven decision making