# Statistics Finland (StatFin) MCP

**Query Finland's official statistics with your AI agent.** Population, economy, labour,
housing, prices, and regional data — straight from Statistics Finland's StatFin database,
delivered as clean, ready-to-read rows. Ask a question in natural language; the server
finds the right table, figures out its structure, and returns the numbers.

> Example: *"What was Finland's population at the end of 2024 and 2025, by sex?"* →
> the agent searches StatFin, reads the table's structure, and answers with the figures.

This package is a lightweight, open **bridge** that connects any MCP client (Claude
Desktop, etc.) to the hosted, maintained Statistics Finland MCP server on Apify. The bridge
holds no data logic — it forwards your requests to the hosted service, which does the hard
part (querying StatFin and decoding its `json-stat2` cubes) and meters usage to your own
Apify account.

## Tools

| Tool | What it does |
|------|--------------|
| `search_tables` | Find statistical tables by keyword (3,000+ tables). |
| `get_table_metadata` | List a table's variables and value codes — how to query it. |
| `get_data` | Get clean, labelled data rows (the dimensional cube decoded for you). |

Covers the whole StatFin database, plus municipal key figures and postal-code-area
(Paavo) data via an optional `database` parameter. Languages: English, Finnish, Swedish.

## Setup

### 1. Get access + an Apify API token

This bridge calls a **hosted, paid Actor** on Apify. You need your own Apify account and
API token:

1. Open the Actor on the Apify Store: **https://apify.com/nectia/statfin-mcp**
2. Subscribe / rent the Actor (usage is billed per call — pay only for what you use).
3. Copy your API token from **Apify Console → Settings → Integrations → API token**.

### 2. Add it to your MCP client

**Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "statfin": {
      "command": "npx",
      "args": ["-y", "statfin-mcp-server"],
      "env": {
        "APIFY_API_TOKEN": "PASTE_YOUR_APIFY_TOKEN_HERE"
      }
    }
  }
}
```

Restart your client. That's it — no build step, no other keys.

## Why hosted?

Statistics Finland's data is open, but building and maintaining a reliable agent
interface is not: table discovery, non-obvious variable codes, and decoding StatFin's
`json-stat2` dimensional responses into flat rows. The hosted Actor does all of that,
stays updated, and you pay only per call — no infrastructure to run.

## How it works

```
Your MCP client  ──stdio──►  statfin-mcp-server (this bridge)  ──HTTPS──►  Hosted Actor on Apify  ──►  StatFin API
```

The bridge authenticates to the hosted Actor with your `APIFY_API_TOKEN` and transparently
proxies the three tools. Your token stays on your machine; Apify meters the calls to your
account.

## Data & attribution

Data © Statistics Finland, StatFin database, licensed **CC BY 4.0**. This project is not
affiliated with or endorsed by Statistics Finland.

## License

MIT © Nectia Automation. The bridge code is open source; the hosted Actor is a commercial
service.