Finnish Legislation (Finlex) MCP

An MCP server that gives an AI agent clean, queryable access to Finnish legislation from Finlex — search statutes by keyword and retrieve them as structured, readable text (title, sections/§, in-force status, ELI), parsed from the Akoma Ntoso legal-XML standard.

Data © Ministry of Justice / Finlex, licensed CC BY 4.0.

Tools

Tool	What it does
search_statutes	Keyword search over statute titles (a bundled index — the Finlex API has no full-text search). Returns statuteRef + title + ELI.
get_statute	Fetch one statute and return it parsed: title, dates, ELI, and sections (§) with headings + text. Defaults to the consolidated (in-force) version, falling back to the original.
list_statutes	Browse recently issued statutes (newest first), optionally by year.

Agents chain them: search → get. Languages: Finnish (fi, default) and Swedish (sv).

Example

"What does Finland's Data Protection Act say?"

1. search_statutes({ query: "tietosuoja" }) → { statuteRef: "2018/1050", title: "Tietosuojalaki", ... }
2. get_statute({ statuteRef: "2018/1050" }) →

{
  "versionReturned": "consolidated",
  "id": "1050/2018",
  "title": "Tietosuojalaki",
  "eli": "http://data.finlex.fi/eli/sd/2018/1050/...",
  "dateIssued": "2018-12-05",
  "sections": [
    { "number": "1 §", "heading": "...", "text": "..." }
  ]
}

Notes & limits

• Search is over titles, not full body text — Finlex's open-data API offers no full-text search, so we ship a bundled title index (src/finlex/index-data.ts, regenerated by npm run build:index). Widen coverage by re-running that script.
• Legislation only for now. Case law (court decisions) is not yet published through the Finlex open-data API; it will be added when it is.

Local use (stdio)

npm install
npm run build

Claude Desktop config:

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

No API key is required — Finlex is open data (a User-Agent header is sent automatically).

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 Finlex calls
npm run build       # produces dist/
npm run build:index # regenerate the bundled statute-title index (throttled crawl)

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) or the npm scripts from PowerShell.

Design

• src/finlex/client.ts — HTTP only (list + retrieve). User-Agent header, throttle + TTL cache, typed FinlexApiError (404/429).
• src/finlex/parse.ts — the moat: Akoma Ntoso XML → clean { title, sections, dates, eli }.
• src/finlex/search.ts + index-data.ts — bundled title index + keyword search.
• 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.