FragDenStaat

fds-mcp — FragDenStaat.de for AI assistants

An [MCP](https://modelcontextprotocol.io) server for [FragDenStaat.de](https://fragdenstaat.de), the German freedom-of-information platform built on [froide](https://github.com/okfde/froide).

*Deutsche Fassung*

Prepare a German freedom-of-information request by asking for it in plain language. Your assistant finds the authority that has to answer and proves why it is the right one, names the act that applies and the deadline it sets, tracks the requests you already sent, collects the replies and their attachments, and writes a new request to a local file that you read before anything leaves your machine.

What is MCP, and what does it do here?

MCP, the Model Context Protocol, is the standard that lets an AI assistant use outside tools — roughly what an extension does for a browser. fds-mcp is one such tool. Install it once and Claude, or any other MCP client, gains 15 tools that speak to FragDenStaat.de, the German freedom-of-information platform built on froide.

Four of them need no account and no token: searching authorities, reading an act, and working out who is responsible for a given place all work straight away.

Other froide instances

froide is the Django software underneath FragDenStaat.de, and its own README names a second production portal: fragdenstaat.at. Point this server at one with

export FDS_MCP_BASE_URL=https://fragdenstaat.at

Only https origins without a path or credentials are accepted, and the host allowlist that keeps the bearer token from following a link to a stranger is derived from this value — so with .at configured, fragdenstaat.de is a foreign host and is refused.

What that buys you, measured against fragdenstaat.at on 2026-09-05 and kept as live tests:

What it looks like

You: Who has to answer a freedom-of-information request about the city of Bonn, and

under which act?

The assistant calls check_jurisdiction("Bonn"), gets the region chain and

Kommunalverwaltung Bonn (authority 3495), then get_authority(3495) for the acts that

apply and their deadlines — and reports the API URLs it used, so you can check the answer

instead of believing it.

Submitting is possible too, but it is deliberately the hardest thing this server does.

⚠️ POST /api/v1/request/ sends immediately and irreversibly

FragDenStaat's REST API has no draft mode, no preview and no undo. The moment a POST /api/v1/request/ succeeds, the e-mail is on its way to the authority, the request is public (by default) under CC0, and it cannot be recalled.

Worse, MakeRequestSerializer has no `law_type` field. The API therefore always files under publicbody.default_law, and because froide sorts by ("-meta", "-priority") that is almost always the *combined meta act* — not the specific act you meant. For a municipality in Rhineland-Palatinate, asking for the LTranspG (law 16) through the API silently files under "LTranspG, VIG" (law 18) instead.

Because of this, the recommended exit of this server is `build_submit_url`, which hands you a prefilled web form with the correct law_type and lets you press send yourself. submit_request exists, defaults to dry_run=True, and refuses unless five independent gates all agree — see Safety model.

Documentation

• What the API can and cannot do — every limit we hit, how we measured it, the dead ends we tried, and the mistakes we made along the way
• OAuth setup, with screenshots — registering the application, scopes, the redirect-URI rules, and what to do when the local HTTPS listener is blocked
• README.de.md and docs/oauth-setup.de.md — the same documents in German. US English is the source; the German version follows it.

Installation

pip install fds-mcp

Or run it without installing anything, straight from PyPI:

uvx fds-mcp serve

From a checkout, for development:

git clone https://github.com/notDIRK/fds-mcp.git

cd fds-mcp pip install -e ".[dev]"

Requires Python 3.10 or newer.

Register it with your MCP client

The server speaks stdio. For Claude Code:

claude mcp add fds -- fds-mcp serve

For a client that reads a JSON config:

{

"mcpServers": { "fds": { "command": "fds-mcp", "args": ["serve"] } } }

Or without installing it at all:

{

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

The four green tools work immediately, with no account and no token.

OAuth setup

The yellow and red tools need an OAuth 2.0 bearer token. FragDenStaat supports exactly two authentication schemes for its API — OAuth2 and session cookies. There is no personal API key and no Basic Auth (froide's own docs/api.rst claims otherwise; it is out of date).

1. Register an application

Log in and open https://fragdenstaat.de/account/applications/register/. All account pages are protected by recent_auth_required, so you may be asked for your password again.

Only the schemes `https` and `fragdenstaat` are accepted. http://localhost/... is rejected at registration time — this is OAUTH2_PROVIDER.ALLOWED_REDIRECT_URI_SCHEMES on the server. That is why the default redirect is an HTTPS loopback listener with a self-signed certificate that fds-mcp generates for you (via openssl), and why the fallback is fragdenstaat://callback with a manual paste.

2. Configure and log in

fds-mcp configure --client-id <your-client-id>

fds-mcp login

login runs Authorization Code + PKCE (S256), opens your browser, and catches the redirect on https://localhost:8765/callback. Your browser will warn about the self-signed certificate — that is the local listener; accept it.

Without a browser or without openssl:

fds-mcp login --manual     # uses fragdenstaat://callback, you paste the URL back

Tokens land in ~/.config/fds-mcp/tokens.json with mode 0600. Refresh happens automatically; refresh tokens are valid for 180 days.

fds-mcp status     # config, token and throttle state

fds-mcp whoami # the authenticated account fds-mcp logout --revoke

Scopes

fds-mcp requests read:user read:request make:request by default. Override with fds-mcp configure --scopes "read:user read:request" if you never want to submit.

Nothing here grants deletion. If you drop make:request, submit_request can never work, and everything else still does.

Tools

All four red tools take dry_run: bool = True.

send_reply_via_browser is the sixteenth tool and is not registered unless FDS_MCP_BROWSER_SEND=1 is set. Without that variable it does not appear in the tool list at all. Read Sending replies before you switch it on.

check_jurisdiction returns its evidence

It walks /georegion/?name= up its part_of chain and asks /publicbody/?regions= at every level, then returns the region chain, the matching authorities, and the list of API URLs it used. That matters in Rhineland-Palatinate, where an *Ortsgemeinde* is often not listed on FragDenStaat at all while the *Verbandsgemeindeverwaltung* that administers it is.

build_submit_url is two-step for long requests

Measured on 2026-09-05: fragdenstaat.de answers GET URLs above roughly 4096 bytes with HTTP 400 (4086 bytes → 200, 4106 bytes → 400). A typical 4000-character request exceeds that once URL-encoded. Above the limit the tool returns a short URL that prefills subject and law_type, plus the body in a .body.txt file next to your draft, which you paste into the form.

What FragDenStaat's API cannot do

These are frontend-only, with no REST equivalent. The server does not pretend otherwise:

• replying to an authority — POST /api/v1/message/ only creates *postal* messages (OnlyPostalMessagesWritable), and subject/content are read-only serializer fields. E-mail replies go through /anfrage/ /send/message/, a CSRF-protected Django view that ignores bearer tokens. See Sending replies;
• choosing the legal basis — no law_type in the serializer;
• drafts — RequestDraft is not registered in the API router;
• setting status, resolution, tags or the law after the fact; publishing a request; filing an objection or escalating to the state information commissioner.

Sending replies

An e-mail reply to an authority cannot be sent through the FragDenStaat API. Not with a different payload, not with an extra scope, not with a better token. Three measurements, taken on 2026-09-05 and kept honest by tests/test_api_contract.py:

1. POST /api/v1/message/ with kind: "email" answers HTTP 400 and reports, under the key kind: *"Nachrichten dieser Art können nicht über die API erstellt werden."* That is froide's OnlyPostalMessagesWritable.
2. The identical call with kind: "post" also answers 400 — the probe deliberately carries an unresolvable request URI, so nothing can be created either way — but it carries no `kind` error. That is the calibration. Without it the first measurement would prove nothing: a 400 could just as well come from the invalid URI, from the e