ishumilin/schwaizer-bfs-mcp

About Schwaizer

SHAPING SWITZERLAND'S AI FUTURE

Empowering Swiss businesses and society through responsible AI adoption.

Founded in 2025, Schwaizer is a non-profit organization dedicated to accelerating the responsible adoption of artificial intelligence across Switzerland.

Website: https://www.schwaizer.ch

Overview

The Schwaizer BFS MCP Server provides programmatic access to statistical data from the Swiss Federal Statistical Office (Bundesamt für Statistik / Office fédéral de la statistique) through the Model Context Protocol (MCP).

This server integrates with three BFS APIs:

• PXWEB API - Main statistical data API with comprehensive datasets
• Swiss Stats Explorer (SSE) API - Modern SDMX-based API for time-series data
• DAM API - Data Asset Management catalog for searching and discovering datasets

Features

• 🔍 Search datasets by keywords, themes, and spatial divisions
• 📊 Retrieve statistical data with flexible filtering options
• 🌍 Multi-language support (German, French, Italian, English)
• 📈 Time-series data access via Swiss Stats Explorer API
• 🗂️ Browse catalog with 21 statistical themes
• 🔧 Metadata exploration to understand dataset structure
• ⚡ Rate limiting handling with automatic retries
• 📝 Structured logging for debugging

Installation

Prerequisites

• Node.js 20.0.0 or higher
• npm or pnpm

Install Dependencies

npm install

Configuration

Copy the example environment file:

cp .env.example .env

Edit .env to customize settings (optional):

# Logging level (debug, info, warn, error)
LOG_LEVEL=info

# Optional: Rate limiting
BFS_REQUEST_DELAY=0
BFS_MAX_RETRIES=3

Usage

Running the Server

npm start

The server runs via stdio and can be integrated with any MCP-compatible client.

Available Tools

Catalog Tools

search_datasets

Search for statistical datasets in the BFS catalog.

Parameters:

• language (optional): Language for results (de, fr, it, en) - default: en
• query (optional): Search term to find in titles and descriptions
• theme (optional): Filter by theme (prodima number)
• spatialDivision (optional): Filter by spatial division level
• publishingYearStart (optional): Filter by publishing year start
• publishingYearEnd (optional): Filter by publishing year end
• limit (optional): Maximum results (1-1000) - default: 50

Example:

{
  "language": "en",
  "query": "students",
  "theme": 900212,
  "limit": 10
}

list_themes

List all available statistical themes (categories).

Parameters:

• language (optional): Language for theme names - default: en

Returns: List of 21 themes with prodima numbers and codes.

get_dataset_info

Get detailed information about a specific dataset.

Parameters:

• numberBfs (optional): BFS number (e.g., "px-x-1502040100_131")
• numberAsset (optional): Asset number
• language (optional): Language for results - default: en

Note: Provide either numberBfs or numberAsset. The BFS number is different for PXWEB and SSE datasets.

Data Tools

get_statistical_data

Retrieve statistical data from the PXWEB API.

Parameters:

• numberBfs (required): BFS number of the dataset
• language (optional): Language for results - default: en
• query (optional): Dimension filters as key-value pairs
• format (optional): Response format (json-stat, json, csv) - default: json-stat

Example:

{
  "numberBfs": "px-x-1502040100_131",
  "language": "en",
  "query": {
    "Jahr": ["40", "41"],
    "Studienstufe": ["2", "3"]
  }
}

get_sse_data

Retrieve time-series data from the Swiss Stats Explorer API.

Parameters:

• numberBfs (required): SSE dataset identifier (e.g., "DF_LWZ_1")
• language (optional): Language for results - default: en
• query (optional): Dimension filters
• startPeriod (optional): Start period (e.g., "2020")
• endPeriod (optional): End period (e.g., "2023")

Note: The BFS number for SSE datasets is different from the PXWEB datasets.

Example:

{
  "numberBfs": "DF_PASTA_552_MONTHLY",
  "language": "en",
  "query": {
    "FREQ": "M",
    "ACCOMMODATION_TYPE": ["552001"],
    "COUNTRY_ORIGIN": ["CH", "AUSL"]
  },
  "startPeriod": "2020",
  "endPeriod": "2023"
}

Metadata Tools

get_dataset_metadata

Get complete metadata structure for a PXWEB dataset.

Parameters:

• numberBfs (required): BFS number of the dataset
• language (optional): Language for labels - default: en

Returns: Complete dimension structure with all codes and values.

get_sse_metadata

Get metadata for a Swiss Stats Explorer dataset.

Parameters:

• numberBfs (required): SSE dataset identifier
• language (optional): Language for labels - default: en

get_dataset_dimensions

Get a simplified view of available dimensions for filtering.

Parameters:

• numberBfs (required): BFS number of the dataset
• language (optional): Language for labels - default: en

Returns: Dimension codes with sample values for quick reference.

Typical Workflow

1. Discover Datasets

// Search for datasets about students
search_datasets({
  "query": "students",
  "language": "en",
  "theme": 900212  // Education theme
})

2. Explore Dataset Structure

// Get metadata to understand available dimensions
get_dataset_metadata({
  "numberBfs": "px-x-1502040100_131",
  "language": "en"
})

3. Retrieve Data

// Get filtered data
get_statistical_data({
  "numberBfs": "px-x-1502040100_131",
  "language": "en",
  "query": {
    "Jahr": ["40", "41"],  // Years 2020/21, 2021/22
    "Geschlecht": ["0", "1"]  // All genders
  }
})

Example Use Case: Demographic Analysis

This section demonstrates a complete workflow for finding and retrieving specific demographic data.

Goal: Find the total permanent resident population of Zurich (ZH), Bern (BE), and Vaud (VD) for the years 2020-2024.

Step 1: Search for Relevant Datasets

First, search for datasets related to population at the cantonal level.

search_datasets({
  "language": "en",
  "query": "population",
  "spatialDivision": "Cantons"
})

This returns a list of datasets. We identify "px-x-0102010000_102" ("Permanent and non-permanent resident population by canton, sex, marital status and age, 2010-2024") as the most relevant one.

Step 2: Get Dataset Metadata

Next, get the metadata to understand the dataset's structure and find the codes for filtering.

get_dataset_metadata({
  "numberBfs": "px-x-0102010000_102",
  "language": "en"
})

From the metadata, we identify the following codes:

• Cantons: ZH, BE, VD
• Population Type: 1 (Permanent resident population)
• Sex: -99999 (Total)
• Marital Status: -99999 (Total)
• Age: -99999 (Total)

Step 3: Retrieve the Data

Finally, use the codes to query the specific data points.

get_statistical_data({
  "language": "en",
  "numberBfs": "px-x-0102010000_102",
  "query": {
    "Jahr": ["2020", "2021", "2022", "2023", "2024"],
    "Kanton": ["ZH", "BE", "VD"],
    "Bevölkerungstyp": "1",
    "Geschlecht": "-99999",
    "Zivilstand": "-99999",
    "Alter": "-99999"
  },
  "format": "json"
})

Step 4: Analyze the Results

The query returns the following data, which can then be used for analysis or visualization.

This workflow demonstrates how to efficiently navigate the BFS data catalog and retrieve precise data for analysis.

BFS Themes

The BFS organizes data into 21 thematic areas:

Rate Limiting

The BFS PXWEB API has rate limits. If you encounter HTTP 429 errors:

1. Add delays between requests: Set BFS_REQUEST_DELAY in .env
2. Query specific dimensions: Instead of requesting all data, filter by specific dimensions
3. Use smaller datasets: Break large queries into smaller chunks

API Documentation

PXWEB API

• Base URL: https://www.pxweb.bfs.admin.ch/api/v1
• Documentation: PXWEB API Guide

Swiss Stats Explorer (SSE)

• Base URL: https://stats.swiss/api/v1
• Format: SDMX-based XML responses

DAM API

• Base URL: https://dam-api.bfs.admin.ch/hub/api
• Purpose: Dataset catalog and metadata

Error Handling

The server provides clear error messages for common issues:

• 404 Not Found: Dataset doesn't exist - check the BFS number
• 429 Too Many Requests: Rate limit exceeded - add delay or reduce query size
• 400 Bad Request: Invalid query parameters - check dimension codes and values
• No records found: Query filters don't match any data - adjust filters or time period

Development

Project Structure

schwaizer-bfs-mcp/
├── src/
│   ├── index.js              # MCP server entry point
│   ├── config.js             # Configuration loader
│   ├── api/                  # API clients
│   │   ├── pxweb-client.js   # PXWEB API
│   │   ├── sse-client.js     # Swiss Stats Explorer
│   │   └── dam-client.js     # DAM catalog
│   ├── tools/                # MCP tool implementations
│   │   ├── catalog-tools.js  # Search & discovery
│   │   ├── data-tools.js     # Data retrieval
│   │   └── metadata-tools.js # Metadata access
│   └── utils/                # Utilities
│       ├── logger.js         # Logging
│       └── formatting.js     # Helpers
├── tests/                    # Test files
├── docs/                     # Documentation
├── .env.example              # Environment template
├── package.json              # Dependencies
└── README.md                 # This file

Scripts

• npm start - Start the MCP server
• npm run dev - Start with auto-reload on file changes
• npm test - Run tests (when implemented)
• npm run lint - Run ESLint
• npm run format - Format code with Prettier

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

MIT License - See LICENSE file for details

Disclaimer

This is an unofficial community project and is not affiliated with or endorsed by the Swiss Federal Statistical Office (BFS/OFS/UST/UFS).

Resources

• BFS Official Website
• BFS Data Catalog
• Swiss Stats Explorer
• Model Context Protocol
• Schwaizer Organization

Support

For issues and questions, please open an issue on the project's GitHub repository.

Built with ❤️ by Schwaizer for the Swiss AI community