🇨🇭 Part of the Swiss Public Data MCP Portfolio

register-mcp

MCP Server for the Swiss Federal Commercial Register (Zefix/Handelsregister), with a company-UID join to the official gazettes (SHAB + cantonal Amtsblätter)

🇩🇪 Deutsche Version

Overview

register-mcp provides AI-native access to two Swiss federal data sources, joined on the UID, all without authentication:

The two sources share one key — the UID. The value is in the join: Zefix tells you whether a company exists; the gazette tells you what has been published about it.

The gazette access here is deliberately company-scoped only — keyed on a company UID or a specific publication id. There is no free-text / person-name gazette search in this server; that would be a profiling tool over the gazette's person-data rubrics (bankruptcy, debt-collection, inheritance). Broad Amtsblatt platform search (procurement, cantonal notices, full-text) is proposed as a separate amtsblatt-mcp — see docs/amtsblatt-mcp-proposal.md and the Data Protection & Scope section below.

Designed for Swiss public administration use cases: vendor verification, contract partner due diligence, and supplier onboarding — all via natural language queries.

Anchor demo query: "Before we sign a framework agreement with Lehrmittelverlag Zürich AG: is the company active in the commercial register, what is its UID and stated purpose — and, via that UID, what has the official gazette published about it (HR mutations, calls to creditors, any bankruptcy)?"

That single question walks the whole tool chain across both sources:

zefix_search_company  →  zefix_verify_company  →  gazette_company_publications(uid=…)  →  gazette_get_publication(id=…)

Features

• 🏛️ 9 tools across two sources — company search & verification (Zefix) + the company-scoped gazette join (SHAB/cantonal)
• 🔗 gazette_company_publications — the UID join: everything published about a company
• 🛡️ Data-protection-safe by construction — the only gazette entry points are UID- or id-scoped; no person-name search entry exists (see Data Protection & Scope)
• 🔍 zefix_verify_company — quick active/dissolved status check
• 🌐 Bilingual output (Markdown / JSON) with per-source attribution + provenance
• 🔓 No API key required — open data from zefix.admin.ch and amtsblattportal.ch
• ☁️ Dual transport — stdio (Claude Desktop) + SSE (cloud)

Prerequisites

• Python 3.11+
• uv (recommended) or pip

Installation

# Clone the repository
git clone https://github.com/malkreide/register-mcp.git
cd register-mcp

# Install
pip install -e .
# or with uv:
uv pip install -e .

Or with uvx (no permanent installation):

uvx register-mcp

Quickstart

# stdio (for Claude Desktop)
python -m register_mcp.server

# SSE (cloud deployment) — MCP_API_KEY is REQUIRED
MCP_API_KEY=$(openssl rand -hex 32) MCP_TRANSPORT=sse PORT=8000 \
  python -m register_mcp.server

SSE / Cloud Deployment

When running with MCP_TRANSPORT=sse, the server enforces:

• Bearer-token auth — set MCP_API_KEY to a secret string. Clients must send Authorization: Bearer <key> on every request. Missing or wrong → HTTP 401. The server refuses to start without MCP_API_KEY set.

• Rate limiting — sliding window per bearer-token hash. Defaults: 60 req / 60 s. Tunable via MCP_RATE_LIMIT and MCP_RATE_WINDOW. Exceeding the limit returns HTTP 429 with Retry-After.

• Structured JSON logging — every tool call emits one line to stderr with tool, status, latency_ms. Auth failures and rate-limit events are logged at WARNING level. Configure verbosity with LOG_LEVEL (default INFO).

• Reference-data cache — Zefix legal-forms are cached for 24h (LEGAL_FORMS_TTL seconds) to avoid an extra upstream call per tool invocation.

• Egress allow-list — outbound HTTP is restricted to www.zefix.admin.ch and amtsblattportal.ch via an httpx request hook that also fires on redirects. A Location header pointing elsewhere raises EgressDenied and is never followed. Override with MCP_ALLOWED_HOSTS=host1,host2 (comma-separated, lower-case).

  ⚠️ Upgrade note (0.2.x → 0.3.0): amtsblattportal.ch was added to the default allow-list when the gazette tools shipped. If your deployment pins MCP_ALLOWED_HOSTS, that value overrides the default entirely — add amtsblattportal.ch to it, or every gazette_* call will raise EgressDenied.

• Optional OpenTelemetry tracing — install with pip install register-mcp[otel] and set OTEL_EXPORTER_OTLP_ENDPOINT (e.g. http://otel-collector:4318/v1/traces). Without the extra or without the env var the server stays silent — no hard dependency on the OTel SDK.

For multi-instance deployments, place a real gateway (Cloudflare, Railway internal networking, an API-Gateway with Redis-backed rate limiting) in front of the in-memory limiter, which is per-process by design.

Container deployment

A minimal multi-stage Dockerfile ships with the repo. The image runs as a non-root mcp user; dependencies are resolved from uv.lock (uv sync --frozen), so the build is reproducible.

docker build -t register-mcp:local .

docker run --rm -p 8000:8000 \
  -e MCP_TRANSPORT=sse \
  -e MCP_API_KEY="$(openssl rand -hex 32)" \
  register-mcp:local

For local iteration there is a compose.yaml with read_only, cap_drop: ALL and no-new-privileges:

MCP_API_KEY=$(openssl rand -hex 32) docker compose up --build

See SECURITY.md for hardening notes (egress restriction, key rotation, SIEM forwarding).

Try it immediately in Claude Desktop:

"Is Lehrmittelverlag Zürich AG active in the commercial register?" "Look up the company with UID CHE-108.954.978" "List all Swiss legal forms"

Configuration

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "register": {
      "command": "python",
      "args": ["-m", "register_mcp.server"]
    }
  }
}

Or with uvx:

{
  "mcpServers": {
    "register": {
      "command": "uvx",
      "args": ["register-mcp"]
    }
  }
}

Config file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Cloud Deployment (SSE for browser access)

For use via claude.ai in the browser (e.g. on managed workstations without local software):

Render.com (recommended):

1. Push/fork the repository to GitHub
2. On render.com: New Web Service → connect GitHub repo
3. Set start command: python -m register_mcp.server --http --port 8000
4. In claude.ai under Settings → MCP Servers, add: https://your-app.onrender.com/sse

💡 "stdio for the developer laptop, SSE for the browser."

Available Tools

Zefix — commercial register (6):

Amtsblattportal — the company-scoped gazette join (3):

The prefix is gazette_, not shab_, because the source covers SHAB and the cantonal gazettes. Every entry point is UID- or id-scoped — see Data Protection & Scope. Broad, non-company gazette search (procurement, cantonal full-text) is scoped to the separate amtsblatt-mcp.

Example Use Cases

Architecture