Openlex MCP

🇨🇭 Part of the [Swiss Public Data MCP Portfolio](https://github.com/malkreide)

⚖️ openlex-mcp

MCP Server for Canton Zurich legislation (ZH-Lex) — full-text search, article extraction, and education law tools for ~970 cantonal laws

🇩🇪 Deutsche Version

---

Overview

openlex-mcp provides AI-native access to the entire legal collection of Canton Zurich (Zürcher Gesetzessammlung). It combines full-text data from HuggingFace with live metadata from the official zh.ch website, storing everything in a local SQLite database with FTS5 full-text indexing for sub-50ms search performance.

Built for the Schulamt (school department) of the City of Zurich, but covers all areas of cantonal law — from tax law to building regulations.

Anchor demo query: *"What does the Volksschulgesetz say about parental involvement? Show me Art. 55 VSG and find all articles that mention 'Elternrat'."*

---

Features

• ⚖️ 8 tools covering search, retrieval, article extraction, and cache management
• 🔍 FTS5 full-text search across ~970 cantonal laws with BM25 ranking
• 📑 Article extraction — parse individual articles (Art. / §) with paragraph detection
• 🏫 Education law shortcuts — specialized search for LS 412.x series (Volksschulgesetz, Lehrpersonalverordnung, etc.)
• 🌐 Live metadata from zh.ch for current validity status and PDF links
• 💾 Hybrid architecture — cached full-text (HuggingFace) + live metadata (zh.ch)
• 🔓 No API key required — all data under open licenses (CC-BY-SA 4.0)
• ☁️ Dual transport — stdio (Claude Desktop) + Streamable HTTP (cloud)

---

Development Phase

Current phase: Phase 1 — Read-Only. All tools are read-only (readOnlyHint: true); no writes to external systems. See ROADMAP.md for the phase plan and transition gates before any write or multi-agent capability is added.

---

Prerequisites

• Python 3.11+
• uv (recommended) or pip
• Internet connection (for initial data download and live metadata)

---

Installation

# Clone the repository

git clone https://github.com/malkreide/openlex-mcp.git cd openlex-mcp

Install

pip install -e .

or with uv:

uv pip install -e .

---

Quickstart

# stdio (for Claude Desktop)

python -m openlex_mcp.server

Streamable HTTP — binds to 127.0.0.1:8000 by default (localhost only)

python -m openlex_mcp.server --http --port 8000

Network binding

By default the HTTP transport binds to `127.0.0.1` (localhost only). The host and port are configurable via the MCP_HOST / MCP_PORT environment variables (or the --host / --port CLI flags, which take precedence).

Never bind to 0.0.0.0 outside a container — it exposes the server to your local network (NeighborJack risk). For containerized/cloud deployments set MCP_HOST=0.0.0.0 explicitly; when that happens outside a detected container the server logs a warning.

Try it immediately in Claude Desktop:

*"What is the Volksschulgesetz (VSG)?"*

*"Find all Zurich laws about data protection"*

*"Show me Art. 1 of the Volksschulgesetz"*

*"Which education laws mention 'Schulleitung'?"*

---

Configuration

Claude Desktop

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

{

"mcpServers": { "openlex": { "command": "python", "args": ["-m", "openlex_mcp.server"] } } }

Or with the installed entry point:

{

"mcpServers": { "openlex": { "command": "openlex-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 openlex_mcp.server --http --port 8000
4. Set environment variable MCP_HOST=0.0.0.0 so the container is reachable (the code default is 127.0.0.1; Render sets the RENDER env var, so no NeighborJack warning is logged)
5. Set MCP_CORS_ORIGINS=https://claude.ai so the browser can read the Mcp-Session-Id header (comma-separated list; no wildcard — defaults to empty, i.e. no cross-origin access)
6. 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

Search & Browse

Article Extraction

Metadata & Cache

Key Legal Area Prefixes (LS Numbers)

Example Use Cases

---

Architecture

┌─────────────────┐     ┌──────────────────────────────┐     ┌──────────────────────────┐

│ Claude / AI │────▶│ OpenLex MCP │────▶│ HuggingFace │ │ (MCP Host) │◀────│ (MCP Server) │◀────│ rcds/swiss_legislation │ └─────────────────┘ │ │ │ (974 ZH laws, cached) │ │ 8 Tools │ ├──────────────────────────┤ │ SQLite + FTS5 Cache │────▶│ zh.ch ZH-Lex │ │ Stdio | HTTP │◀────│ (live metadata + PDFs) │ │ │ ├──────────────────────────┤ │ No authentication required │ │ LexFind.ch │ └──────────────────────────────┘ │ (links only) │ └──────────────────────────┘

Data Source Characteristics

Design Decision: Tools-only (no MCP Resources)

All 8 endpoints are exposed as Tools rather than MCP Resources. Rationale:

• Every lookup is parametric — queries, abbreviations, article numbers vary per call. Static Resources (one URI per document) don't capture this naturally.
• The corpus is 974 laws × many articles — registering each as a Resource URI would create an impractically large resource list.
• MCP Resource templates (zhlex://laws/{sr_number}) are a future consideration for Phase 2 if clients benefit from resource-level caching or subscriptions.

Scaling Constraints

The constraint depends on the protocol era the client speaks:

• `2026-07-28` (modern) — every request is a self-contained POST carrying its own _meta envelope; the server answers without issuing an Mcp-Session-Id and keeps no session between requests. Any replica can answer any request; no shared store, no sticky routing. (subscriptions/listen streams live on the replica that opened them — this server's lists are fixed at import, so there is nothing to fan out.)
• Handshake era (`initialize`, up to `2025-11-25`) — session state is kept in-process. Multiple replicas break active sessions because there is no shared session store (Redis, Durable Objects, etc.). A single-replica Render deployment routes all requests to one process, so no sticky-session LB is needed today.

Before scaling handshake-era clients beyond one instance: either add a shared session store or configure your edge load balancer to route on the Mcp-Session-Id header with a stick-table and an appropriate TTL.

---

MCP Protocol Version

Update policy

1. When mcp is upgraded (via Dependabot PR), verify the protocol version in the SDK release notes.
2. If the protocol version changes, update MCP_PROTOCOL_VERSION in server.py, regenerate docs/tool-hashes.json (PYTHONPATH=src python scripts/gen_tool_hashes.py --write), and note the change in CHANGELOG.md.
3. Run pytest tests/ -m "not live" to confirm compatibility before merging.

---

Project Structure

openlex-mcp/

├── src/openlex_mcp/ │ ├── init.py # Pa