kolada-mcp

# 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 ```bash pip install -e . ``` ### Using Docker ```bash docker-compose up -d kolada-mcp ``` ## Usage ### Stdio Mode (Default) ```bash kolada-mcp # or python -m kolada_mcp ``` ### HTTP Mode ```bash MCP_TRANSPORT=http PORT=8001 kolada-mcp ``` ### Claude Desktop Integration Add to your Claude Desktop configuration: ```json { "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 ```bash # Create virtual environment python -m venv .venv source .venv/bin/activate # Install with dev dependencies pip install -e ".[dev]" ``` ### Running Tests ```bash pytest ``` ### Code Quality ```bash # 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