scb-mcp

An MCP server over Statistics Sweden's business register. Point an assistant at it and it can search, count and read Swedish workplaces and legal entities without knowing anything about cursors, path versions or API keys.

No dependencies. The protocol is implemented against the specification rather than wrapped, which is the point: the handshake, the framing and the error codes are all in src/, in about three hundred lines you can read.

Use it

// Claude Desktop, claude_desktop_config.json
{
  "mcpServers": {
    "scb": {
      "command": "npx",
      "args": ["-y", "scb-mcp"],
      "env": { "SCB_API_KEY": "the key you were given" }
    }
  }
}

The key goes in the environment, never on the command line and never in a path. It travels in the X-API-Key header that the register's contract asks for, and it is not written to the log.

Related MCP server: SCB MCP Server

The tools

Every search takes limit and follows the register's cursor until it has that many. full: true asks for every available variable instead of the usual selection.

See it work

node --experimental-strip-types examples/handshake.ts

A stubbed register, the real protocol:

-> {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}
<- {"protocolVersion":"2024-11-05","capabilities":{"tools":{"listChanged":false}},"serverInfo":{"name":"scb-mcp","version":"0.1.0"}}
-> {"jsonrpc":"2.0","method":"notifications/initialized"}
   (notification, nothing to answer)
-> {"jsonrpc":"2.0","id":2,"method":"tools/list"}
<- 6 tools: search_workplaces, count_workplaces, get_workplace, search_legal_entities, count_legal_entities, get_legal_entity
-> {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"count_workplaces","arguments":{"...
<- ok: { "count": 1403 }
-> {"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"search_workplaces","arguments":{...
<- ok: { "count": 2, "hasMore": true, "items": [ { "cfarNr": "10000001", "namn": "Nordvik Bygg AB", "kommun": "0486",
-> {"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"get_workplace","arguments":{"cfa...
<- tool error: no such resource in the register: {"message":"unknown path"}

Three decisions

A tool that fails is a result, not a protocol error. The last line above is a 404 from the register, and it comes back inside tools/call with isError: true. A model reads that and tries a different identifier. A JSON-RPC error would take the whole turn down for something the model could have handled.

Paging is not the model's problem. The register hands out pages with limit and cursorId and says hasMore when there is more. The search tools follow that until they have what was asked for and report whether anything was left, so a model never has to hold a cursor across turns.

The register filters on one thing at a time. That is the API's restriction, not this server's, and giving two filters comes back as the register filters on one thing at a time; kommun and lan were both given rather than one of them being dropped quietly.

Development

npm run check    # types
npm test         # 56 tests, no network, no key
npm run build

fetch is injected into the client, which is why every test runs offline. The register's own contract is at apiafr.scb.se; the paths here follow it, including the /v1 segment and the /count and /full variants.

MIT licensed.