mcp-austrian-firmenbuch

MCP server exposing the Austrian Firmenbuch (Austrian Business Register / Company Register) via the official BMJ FBW-WebServices (HVD) SOAP API, as High Value Datasets under Commission Implementing Regulation (EU) 2023/138.

Implemented against the official interface specification FBW-WebServices (HVD) Schnittstellenbeschreibung, Version 1.3 (22.05.2025).

Requirements

• Python 3.10+

• mcp>=1,<2 (FastMCP API)

• A valid JustizOnline IWG API token (see below)

Related MCP server: Brreg MCP Server

API key — how to request one

The API is free of charge, but every call (including the WSDL) requires a token. To obtain one:

1. You need an ID Austria account.

2. Log in to JustizOnline with your ID Austria.

3. Go to Information on the Reuse of Information (IWG) and click the tile "Antrag auf Informationsweiterverwendung" ("Application for information reuse") — direct link: https://justizonline.gv.at/jop/web/iwg/register

4. Apply for the API "Company data in accordance with Annex 5 of Commission Implementing Regulation (EU) 2023/138 … (High Value Datasets (HVD) of the Business Register)" (internal code FBW). The application is decided by the Federal Ministry of Justice (BMJ).

5. Once approved, your token appears on JustizOnline under your profile, tab "Informationsweiterverwendung" ("Information Reuse").

Set the token as FIRMENBUCH_API_KEY in your environment (or a repo-local .env — see .env.example). The server sends it as the X-API-KEY request header on every SOAP call.

Setup

python3 -m venv .venv && source .venv/bin/activate
pip install "mcp>=1,<2"
cp .env.example .env   # put your token into .env

Note (this workspace): builder/repos/ sits on a filesystem that rejects symlinks, so in-repo venvs cannot be created. Use uv venv /opt/hermes/.local/opt/mcp-firmenbuch-venv + uv pip install --python /opt/hermes/.local/opt/mcp-firmenbuch-venv/bin/python -e . instead; tests run with that interpreter.

Run

python server.py            # stdio MCP server
python server.py --http     # or HTTP streamable on :8000/mcp

MCP client registration (stdio)

{
  "mcpServers": {
    "firmenbuch": {
      "command": "python",
      "args": ["/path/to/mcp-austrian-firmenbuch/server.py"],
      "env": { "FIRMENBUCH_API_KEY": "<your-token>" }
    }
  }
}

Tools

Identifiers

• Firmenbuchnummer (FNR): up to 6 digits plus a check letter, e.g. 419999x or 58468 h (spaces are tolerated).

• Urkunde KEY: e.g. 304188_0070711322495_000___000_30_7730290_XML (returned by suche_urkunde / veraenderungen_urkunde).

Technical notes

• Endpoint: https://justizonline.gv.at/jop/api/at.gv.justiz.fbw/ws

• WSDL: https://justizonline.gv.at/jop/api/at.gv.justiz.fbw/ws/fbw.wsdl (also key-protected)

• SOAP 1.2 (Content-Type: application/soap+xml;charset=UTF-8), header X-API-KEY

• Rate limiting: HTTP 429 Too Many Requests when exceeded — the server surfaces this as a clear error instead of retry-storming.

• SOAP faults inside HTTP 5xx error bodies are decoded and surfaced with their German reason text (e.g. "Der Zeitraum darf 7 Tage nicht überschreiten" for veraenderungen ranges > 7 days, "Zugriff nicht erlaubt!" when the token's HVD scope does not cover an operation).

• All tools accept the raw XML string in the response body (raw=True) if you need fields this server does not parse out.

Data license / terms: use under the JustizOnline IWG terms of use (https://justizonline.gv.at/jop/web/iwg/terms). Cite the source (BMJ Firmenbuch) when republishing.

Tests

python -m pytest -q

Unit tests cover XML envelope building and response parsing against fixtures derived from the official spec examples — no live API access needed.

License

Licensed under the Apache License, Version 2.0 — see LICENSE.

Not affiliated with the BMJ / JustizOnline / the Austrian Commercial Register. The Firmenbuch data obtained through this server is not covered by this license: users are responsible for complying with the JustizOnline IWG terms of use (https://justizonline.gv.at/jop/web/iwg/terms) when consuming or republishing register data. Each user brings their own API token.