fds-mcp — FragDenStaat.de for AI assistants

An MCP server for FragDenStaat.de, the German freedom-of-information platform built on 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=<place> up its part_of chain and asks /publicbody/?regions=<id> 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.