Kolada MCP Server

A clean, standalone MCP (Model Context Protocol) server for Sweden's Kolada municipal statistics API.

Overview

This server provides AI applications with access to Sweden's comprehensive municipal and regional statistics database. It enables natural language queries against thousands of Key Performance Indicators (KPIs) covering various aspects of Swedish public sector data.

Features

• 9 MCP Tools for comprehensive data access
• Semantic Search using Swedish BERT embeddings
• No External Dependencies - fully standalone (no Mima or Redis)
• Containerized with Docker support
• Modern Python 3.11+ with type hints and async/await

Available Tools

Tool	Description
list_operating_areas	List all KPI categories with counts
get_kpis_by_operating_area	Get KPIs within a specific category
search_kpis	Semantic search for KPIs using natural language
get_kpi_metadata	Get detailed metadata for a specific KPI
fetch_kolada_data	Fetch raw KPI data for municipalities
analyze_kpi_across_municipalities	Comparative analysis with rankings
compare_kpis	Compare two KPIs (difference or correlation)
list_municipalities	List municipalities/regions
filter_municipalities_by_kpi	Filter by KPI threshold

Installation

Using pip

pip install -e .

Using Docker

docker-compose up -d kolada-mcp

Usage

Stdio Mode (Default)

kolada-mcp
# or
python -m kolada_mcp

HTTP Mode

MCP_TRANSPORT=http PORT=8001 kolada-mcp

Claude Desktop Integration

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "kolada": {
      "command": "kolada-mcp"
    }
  }
}

Configuration

Environment variables:

Variable	Default	Description
MCP_TRANSPORT	stdio	Transport mode (stdio or http)
PORT	8001	HTTP server port
LOG_LEVEL	INFO	Logging level

Development

Setup

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install with dev dependencies
pip install -e ".[dev]"

Running Tests

pytest

Code Quality

# Linting
ruff check src tests

# Type checking
mypy src

Architecture

src/kolada_mcp/
├── __init__.py          # Package init
├── __main__.py          # Entry point
├── config.py            # Settings (Pydantic)
├── server.py            # FastMCP server
├── models/
│   └── types.py         # Data models
├── services/
│   ├── kolada_client.py # API client
│   ├── embeddings.py    # Semantic search
│   └── data_processing.py
└── tools/
    ├── metadata.py      # KPI metadata tools
    ├── data.py          # Data fetching tools
    ├── municipality.py  # Municipality tools
    └── comparison.py    # Comparison tools

License

Apache-2.0