normkompass-mcp

A small MCP server in Python that lets an AI agent search German federal law and ask cited questions through normkompass, a TypeScript RAG service that answers only with verifiable citations and refuses when the corpus does not support an answer.

Status: reference implementation, version 0.1.0. It is a thin client: it adds no retrieval, no model and no storage. Not legal advice.

Tools

• Refusal is a normal result, not an error. When normkompass finds no answer that its citation check supports, the agent gets refused: true. The quote checking (every quote a verbatim part of a retrieved passage) happens in normkompass; this server passes the citations through exactly as returned and discards an answer that comes without one.

• Errors are short tool errors: invalid input (nothing is sent to the API), API not reachable (names the configured address), timeout (30 s for search, 120 s for ask, no silent retry), a response in an unexpected shape, and an API without an answer model (ask_law fails, search_law still works).

• The server starts and lists its tools even when the API is down; the failure shows when a tool is called.

Related MCP server: Legal MCP

Requirements

• A running normkompass API (see its README; default address http://localhost:3000). ask_law additionally needs an answer model configured there.

• Python 3.12 or newer and uv.

Set NORMKOMPASS_API_URL if the API is elsewhere (see .env.example). No secrets are read or stored. The server sends requests only to that address; what normkompass does with a question (for example sending it to a hosted answer model) is described in its README.

Connect it to an MCP client

The server speaks MCP over stdio. The command is the same for every client:

uv run --directory /path/to/normkompass-mcp normkompass-mcp

Claude Code:

claude mcp add normkompass -e NORMKOMPASS_API_URL=http://localhost:3000 -- \
  uv run --directory /path/to/normkompass-mcp normkompass-mcp

A client configured through JSON (for example Claude Desktop) takes the same command in its mcpServers entry:

{
  "mcpServers": {
    "normkompass": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/normkompass-mcp", "normkompass-mcp"],
      "env": { "NORMKOMPASS_API_URL": "http://localhost:3000" }
    }
  }
}

What has been run

On 2026-11-05 the server was started with that command (uv run normkompass-mcp) by the MCP Python SDK's client over stdio against a live normkompass API with the default search and the answer model gemini-3.5-flash-lite (free hosted tier, a third party). The client listed the two tools; search_law returned § 18 Abs. 10 UStG and § 1b Abs. 3 UStG for "Wann gilt ein Landfahrzeug als neu?"; ask_law answered that question with the citation § 1b Abs. 3 and refused "Wie hoch ist der gesetzliche Mindestlohn pro Stunde?".

Not run: the two snippets above were not run in Claude Code or Claude Desktop themselves. They use the documented configuration shape with the command that was run. If a client rejects them, that is a bug in this page; please open an issue.

Development

uv sync
uv run ruff format --check . && uv run ruff check . && uv run mypy && uv run pytest

Tests run against a stub of the normkompass API (33 tests, no corpus, database or model needed), including a test that starts the server as a subprocess over stdio. CI runs the same checks plus openspec validate --strict. Work follows OpenSpec: the specification in openspec/ was merged as a separate pull request before any code.

Limits

• Answer quality is that of normkompass and its model; nothing about quality is measured here. See the normkompass README ("Honest limits") for what is known, in particular that Claude has not been measured there.

• stdio only: no remote hosting, no authentication, no caching.

• One corpus (five German federal laws, a snapshot with the Stand shown per result). No promise that the law shown is current or complete.

License

MIT, see LICENSE.