Kela MCP Server

Kela MCP Server

An open-source knowledge server that helps AI assistants answer questions about Finnish social benefits (Kela). Works with any AI assistant that supports the Model Context Protocol. Note! This is a hobby project to demonstrate how to create MCP's.

You: "Can I get housing allowance if I earn 1400€/month in Helsinki?"

AI:  Let me check that for you...
     [calls kela-mcp → check_eligibility]

     Based on current asumistuki rules, with 1400€/month income in Helsinki:
     - You may be eligible for partial housing allowance
     - Estimated amount: 150-280€/month depending on rent and household size
     - Apply through OmaKela with form AT1

     This is informational only. Verify at kela.fi

---

What is MCP?

Model Context Protocol (MCP) is an open standard that lets AI assistants use external tools and data sources. Think of it like giving your AI assistant "superpowers", instead of relying only on its training data, it can call real tools to look things up, do calculations, or take actions.

┌─────────────────┐                      ┌─────────────────┐
│                 │   "What is           │                 │
│  AI Assistant   │    kuntoutustuki?"   │   Kela MCP      │
│  (Claude, etc.) │ ───────────────────► │   Server        │
│                 │                      │                 │
│                 │ ◄─────────────────── │  [looks up      │
│                 │   {eligibility,      │   real data]    │
│                 │    amounts, ...}     │                 │
└─────────────────┘                      └─────────────────┘

Without MCP: AI answers from memory (may be outdated or wrong) With MCP: AI calls this server to get current, structured information

MCP is an open protocol - not tied to any specific AI company. Any AI assistant that implements MCP can use this server.

---

What This Server Provides

Tools (things the AI can do)

| Tool | What it does | Example | |------|--------------|---------| | search_benefits | Find relevant benefits | "help for unemployed students" | | get_benefit_details | Get full info on one benefit | "tell me about opintotuki" | | check_eligibility | Estimate if you qualify | "can I get asumistuki with X income?" | | get_application_steps | How to apply | "how do I apply for sairauspäiväraha?" | | compare_benefits | Side-by-side comparison | "difference between X and Y?" |

Resources (data the AI can browse)

| Resource | Contents | |----------|----------| | kela://benefits | List of all benefit categories | | kela://benefits/{id} | Detailed info for one benefit | | kela://updates | Recent changes to benefits |

Supported Benefits (MVP)

• Asumistuki - Housing allowance
• Opintotuki - Student financial aid
• Sairauspäiväraha - Sickness allowance
• Työttömyysturva - Unemployment benefits
• Kuntoutustuki - Rehabilitation subsidy
• Vanhempainpäiväraha - Parental allowance
• Toimeentulotuki - Social assistance
• Eläkkeet - Pensions (overview)

---

Quick Start

Prerequisites

• Python 3.11 or newer
• An MCP-compatible AI client (see Supported Clients)

Installation

# Clone the repository
git clone https://github.com/emmakingdev/kela-mcp.git
cd kela-mcp

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install the package
pip install -e .

# Build the search index
python scripts/build_db.py

Verify it works

# Run the server directly to test
python -m kela_mcp.server

# You should see:
# Kela MCP Server running...
# Press Ctrl+C to stop

---

Supported Clients

MCP is an open protocol. Here's how to connect this server to popular AI clients:

Claude Desktop

Edit your Claude Desktop config file:

macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "kela": {
      "command": "python",
      "args": ["-m", "kela_mcp.server"],
      "cwd": "/full/path/to/kela-mcp"
    }
  }
}

Restart Claude Desktop. You should see "kela" in the MCP servers list. If it fails, create the venv again.

Claude Code (CLI)

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "kela": {
      "command": "python",
      "args": ["-m", "kela_mcp.server"],
      "cwd": "/full/path/to/kela-mcp"
    }
  }
}

Other MCP Clients

Any client that implements the MCP specification should work. The server uses stdio transport by default (the most widely supported).

For clients that need HTTP/SSE transport:

# Install with SSE support
pip install -e ".[sse]"

# Run with SSE transport
python -m kela_mcp.server --transport sse --port 8080

Building Your Own Client

If you're building an AI application and want to integrate this server, see the MCP Documentation for client implementation guides in various languages.

---

Usage Examples

Once connected, just ask your AI assistant about Kela benefits in natural language:

In Finnish

"Mitä tukia voin saada opiskelijana?"
"Kuinka paljon asumistukea voin saada jos vuokra on 600€?"
"Miten haen sairauspäivärahaa?"

In English

"What benefits can I get as a student in Finland?"
"Am I eligible for housing allowance with 1500€ income?"
"How do I apply for parental leave benefits?"

The AI will automatically use the appropriate tools from this server to answer.

---

Project Structure

kela-mcp/
├── src/
│   └── kela_mcp/
│       ├── __init__.py
│       ├── server.py          # MCP server entry point
│       ├── tools/             # Tool implementations
│       │   ├── search.py
│       │   ├── details.py
│       │   ├── eligibility.py
│       │   └── application.py
│       ├── resources.py       # MCP resources
│       ├── prompts.py         # Prompt templates
│       └── db.py              # Database interface
├── data/
│   ├── benefits/              # Benefit data (JSON)
│   │   ├── asumistuki.json
│   │   ├── opintotuki.json
│   │   └── ...
│   └── kela.db                # Search index (SQLite)
├── scripts/
│   ├── build_db.py            # Build search index
│   └── validate_data.py       # Validate benefit data
├── tests/
├── pyproject.toml
└── README.md

---

Data Sources & Accuracy

All information comes from publicly available sources on kela.fi.

Important Disclaimers

This is NOT official Kela guidance.

• Benefits rules change frequently
• Individual circumstances vary
• Always verify information at kela.fi or contact Kela directly
• This tool provides general information to help you understand your options

Data Freshness

Each benefit entry includes a last_updated timestamp. We aim to review data quarterly, but cannot guarantee real-time accuracy.

---

Development

Running Tests

pytest tests/

Adding a New Tool

1. Create a new file in src/kela_mcp/tools/
2. Implement the tool function with @server.tool() decorator
3. Register it in server.py
4. Add tests in tests/

Local Development with Hot Reload

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

# Run with auto-reload (requires watchdog)
watchmedo auto-restart --patterns="*.py" --recursive -- python -m kela_mcp.server

---

FAQ

Why MCP instead of a regular API?

MCP allows AI assistants to intelligently choose which tools to use based on the conversation. Instead of you manually calling an API, you just ask a question and the AI figures out what information it needs.

Can I use this without an AI assistant?

The server is designed for MCP clients, but the underlying data is plain JSON. You can directly read the files in data/benefits/ or query data/kela.db with SQL.

Is this affiliated with Kela?

No. This is an independent open-source project. We aggregate publicly available information to make it more accessible.

Why Finnish benefits specifically?

The Finnish benefits system is complex and navigating it can be confusing, especially for immigrants or people unfamiliar with the system. This tool helps make that information more accessible.

---

License

MIT License - see LICENSE for details.

---

Acknowledgments

• Model Context Protocol - The open standard that makes this possible
• Kela - For providing comprehensive public documentation
• Contributors who help keep the data accurate

---

Links

• MCP Specification
• MCP Python SDK
• Kela.fi - Official source