Statistics Finland (StatFin) MCP

An MCP server that gives an AI agent clean, queryable access to Statistics Finland's StatFin database — 3,000+ official statistical tables on population, economy, labour, housing, prices, and regions. The server does the hard part: it turns StatFin's dimensional json-stat2 cubes into flat, labelled rows an agent can read directly.

Data © Statistics Finland, StatFin database, licensed CC BY 4.0.

Tools

Tool	What it does
search_tables	Find tables by keyword. Returns a ready-to-use table path (e.g. vaerak/11rb.px), title, and publication date.
get_table_metadata	List a table's variables (dimensions) and their value codes + labels — the codes you need to query. Flags time and eliminable variables.
get_data	Query a table and get flattened, labelled rows (json-stat2 decoded for you). Oversize selections (>100,000 cells) are refused with a hint to narrow.

Agents chain them: search → metadata (learn the codes) → data.

Every tool takes an optional database (default StatFin; also Kuntien_avainluvut, Postinumeroalueittainen_avoin_tieto, StatFin_Passiivi) and language (en/fi/sv).

Example

"What was Finland's population at the end of 2024 and 2025, by sex?"

1. search_tables({ query: "population" }) → finds vaerak/11rb.px.
2. get_table_metadata({ table: "vaerak/11rb.px" }) → variables timeperiod_y (Year), sukupuoli_9_20180101 (Sex, values SSS/1/2), contentscode.

3. get_data({ table: "vaerak/11rb.px", selections: { timeperiod_y: ["2024","2025"], sukupuoli_9_20180101: ["SSS","1","2"], contentscode: ["vaerak-vaesto"] } })
   →

{
  "label": "Population 31.12. by Year, Sex and Information",
  "source": "Statistics Finland, population structure",
  "rowCount": 6,
  "dimensions": [
    { "code": "timeperiod_y", "label": "Year", "size": 2 },
    { "code": "sukupuoli_9_20180101", "label": "Sex", "size": 3 },
    { "code": "contentscode", "label": "Information", "size": 1 }
  ],
  "rows": [
    { "Year": "2024", "Sex": "Total", "Information": "Population 31 Dec", "value": 5635971 },
    { "Year": "2024", "Sex": "Males", "Information": "Population 31 Dec", "value": 2790772 },
    { "Year": "2024", "Sex": "Females", "Information": "Population 31 Dec", "value": 2845199 }
  ]
}

Local use (stdio)

npm install
npm run build

Claude Desktop config:

{
  "mcpServers": {
    "statfin": {
      "command": "node",
      "args": ["/absolute/path/to/servers/statfin/dist/server.js"]
    }
  }
}

No API key is required — StatFin is open data.

Development

npm run typecheck   # tsc --noEmit
npm test            # vitest — unit tests vs recorded real fixtures (offline)
npm run smoke       # live: boots the server, real MCP handshake + real StatFin calls
npm run build       # produces dist/

Windows note: this repo lives under a path with spaces, which breaks npm's .bin shims. Run tools directly (node ./node_modules/vitest/vitest.mjs run, node ./node_modules/typescript/bin/tsc) or run the npm scripts from PowerShell.

Design

• src/statfin/client.ts — HTTP only (GET search + metadata, POST data). Throttle (~1 req/1.5 s, under the 40 req/60 s limit) + short TTL cache. Typed StatFinApiError.
• src/statfin/normalize.ts — the product: tidy search hits, flatten metadata, and decode json-stat2 cubes into flat rows.
• src/statfin/query.ts — build a PxWeb query from a simple { code: values[] } selection; validate codes, expand *, aggregate eliminable variables, and guard the cell limit before hitting the network.
• src/tools.ts — the 3 MCP tools + Pay-Per-Event billing hook.
• src/server.ts (stdio) / src/standby.ts (Apify HTTP) — both call one factory.