DIP Parliamentary Analyser

DIP Parliamentary Analyser answers questions about German Bundestag composition using live open data and a conversational AI interface.

A production oriented proof-of-concept that connects to the German Bundestag DIP API, analyses Fraktion (parliamentary group) membership distribution, and exposes the analysis through an MCP (Model Context Protocol) server with Groq LLM tool-calling.

Project Overview

The system fetches real politician data from the official German Bundestag open-data API, determines each politician's Fraktion membership, computes percentage distribution across all parliamentary groups, and uses a large language model to generate a human-readable German-language summary.

Three core interaction modes (task requirements):

• analyse — one-shot CLI command that fetches data, computes distribution, and generates an LLM summary

• serve — exposes MCP tools over stdio transport so any MCP-compatible client (e.g. Claude Desktop) can call them

• chat — interactive REPL where the LLM automatically selects and calls the right tool based on your natural language question

Key technologies: Python 3.11, FastMCP, Groq (llama-3.3-70b-versatile), httpx, Pydantic v2, Rich, Typer, Poetry, Docker.

Related MCP server: parlament-mcp

Requirement Mapping

Prerequisites

Where to get your keys:

• DIP API key: Register at dip.bundestag.de or use the public demo key available in the portal documentation.

• Groq API key: Create a free account at console.groq.com and generate an API key under API Keys.

Installation

# 1. Clone the repository
git clone https://github.com/Indrasena-reddy/DIP-mcp.git
cd DIP-mcp

# 2. Copy the environment file and fill in your API keys
cp .env.example .env        # Linux/Mac
copy .env.example .env      # Windows

# 3. Install dependencies
poetry install

Open .env and replace the placeholder values:

DIP_API_KEY=your_dip_api_key_here
GROQ_API_KEY=your_groq_api_key_here

Configuration

All configuration is read from environment variables (or the .env file). Never commit .env to version control — it is listed in .gitignore.

Usage

Analyse — fetch distribution and generate LLM summary

poetry run dip-mcp analyse --wahlperiode 20

Fetches all politicians for Wahlperiode 20 (2021–2025), computes the Fraktion distribution table, and generates a German-language summary via Groq. The --wahlperiode / -w flag accepts any valid election period number.

# Example: analyse Wahlperiode 19 (2017–2021)
poetry run dip-mcp analyse --wahlperiode 19

Serve — start the MCP server

poetry run dip-mcp serve

Starts the MCP server on stdio transport (MCP-compliant). Connect any MCP-compatible client (e.g. Claude Desktop, an MCP inspector) to this process. Two tools are registered:

Chat — interactive natural language assistant

poetry run dip-mcp chat

Starts an interactive REPL. Ask questions in natural language (German or English). The LLM automatically selects the correct tool, fetches live data from the DIP API, and returns a formatted answer.

Example questions:

• Wie ist die Fraktionsverteilung in der 20. Wahlperiode?

• Wer ist Friedrich Merz?

• Which parties are in the Bundestag?

Type exit, quit, or press Ctrl+C to quit.

Example Output

analyse — Fraktion distribution table

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━┓
┃ Fraktion                         ┃ Persons ┃ Percentage ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━┩
│ CDU/CSU                          │     197 │     26.50% │
│ SPD                              │     206 │     27.72% │
│ AfD                              │      83 │     11.17% │
│ FDP                              │      92 │     12.38% │
│ DIE LINKE.                       │      38 │      5.11% │
│ BÜNDNIS 90/DIE GRÜNEN            │     118 │     15.88% │
│ fraktionslos                     │       9 │      1.21% │
└──────────────────────────────────┴─────────┴────────────┘
Total: 743 persons (9 unaffiliated)

Followed by a German-language AI summary generated by Groq.

chat — natural language Q&A

You: Who is Friedrich Merz?

BundesBot: Friedrich Merz (born 11 November 1955 in Brilon) is a German politician
and member of the CDU/CSU Fraktion in the 20th Wahlperiode. He has served as a
lawyer and has been a member of the Bundestag since 2021.

You: Wie ist die Fraktionsverteilung in der 20. Wahlperiode?

BundesBot: In der 20. Wahlperiode (2021–2025) verteilen sich die 743 Mitglieder
des Deutschen Bundestages wie folgt: SPD 27,72 %, CDU/CSU 26,50 %,
BÜNDNIS 90/DIE GRÜNEN 15,88 %, FDP 12,38 %, AfD 11,17 %,
DIE LINKE. 5,11 % und 9 fraktionslose Abgeordnete (1,21 %).

Architecture

System diagram

flowchart TD
    User([User])
    CLI["CLI\nanalyse · chat · serve"]
    Groq["Groq LLM\nllama-3.3-70b"]
    MCP["MCP Server\nFastMCP · stdio"]
    DIP[("Bundestag\nDIP API")]

    User --> CLI
    CLI --> Groq
    CLI --> MCP
    Groq <-->|tool-calling| MCP
    MCP --> DIP

The system is organised into four independent layers:

DIP API layer (api/) — An async httpx client with cursor-based pagination, a tenacity retry decorator (retries only on 5xx server errors), and an anyio semaphore for bounded concurrency. Pydantic v2 validates every document returned by the API.

Analytics layer (core/) — Pure Python functions that count Fraktion membership using a Counter, calculate percentage shares, and build a validated DistributionReport model. No external dependencies.

MCP layer (mcp/) — A FastMCP server that exposes two tools over stdio transport. All tool calls — both from the chat REPL and from external MCP clients — are routed through FastMCP.call_tool(), so every invocation genuinely flows through the MCP protocol layer. Person data is cached in-process per Wahlperiode to avoid redundant API fetches.

LLM layer (llm/) — An async Groq client that supports two interaction patterns: (1) single-shot summarisation of a finished distribution report, and (2) multi-turn tool-calling where Groq selects which MCP tool to invoke and composes the final answer from the tool result.

Data flow (chat mode)

User question
    → Groq (tool selection)          — first LLM call
    → _dispatch_tool()
    → FastMCP.call_tool()            — MCP protocol layer
    → tools.py (_get_persons cache)
        → DipApiClient → DIP API     — cursor-paginated fetch (first request only)
        → client-side WP filter      — keeps only members of requested period
    → analytics.py                   — WP-specific Fraktion distribution
    → Groq (answer composition)      — second LLM call
    → displayed to user

Project structure

src/dip_mcp/
├── api/
│   ├── client.py       # Async DIP API client with pagination and retries
│   └── models.py       # Pydantic v2 data models
├── cli/
│   ├── app.py          # Typer root application and command registration
│   ├── analyse.py      # analyse command — end-to-end pipeline
│   └── chat.py         # chat command — interactive MCP tool-calling REPL
├── core/
│   └── analytics.py    # Fraktion counting and percentage calculation
├── llm/
│   └── groq_client.py  # Groq async client — summarisation and tool-calling
├── mcp/
│   ├── server.py       # FastMCP server with two registered tools
│   └── tools.py        # Business logic functions called by MCP tools
└── config.py           # Pydantic Settings — env var loading and validation

Testing

The test suite covers the four core layers with no real API keys required — conftest.py injects placeholder credentials before any module is imported.

poetry run pytest tests/ -v

Extras

The following were built beyond the task requirements.

Docker

A multi-stage Docker image is published to GHCR. No Python or Poetry installation needed.

# 1. Create your .env file
cp .env.example .env        # Linux/Mac
copy .env.example .env      # Windows
# then fill in DIP_API_KEY and GROQ_API_KEY

# 2. Pull and run
docker run --env-file .env ghcr.io/indrasena-reddy/dip-mcp:latest

# Run a specific Wahlperiode
docker run --env-file .env ghcr.io/indrasena-reddy/dip-mcp:latest analyse --wahlperiode 19

# Interactive chat (requires a TTY)
docker run --env-file .env -it ghcr.io/indrasena-reddy/dip-mcp:latest chat

Docker Compose

docker compose up

Builds the image locally and runs analyse --wahlperiode 20 by default.

# Interactive chat via Compose
docker compose run --rm -it dip-mcp chat

BundesBot — Streamlit chat UI

A conversational web interface for asking natural language questions about the Bundestag.

poetry run streamlit run frontend/app.py

Opens at http://localhost:8501. BundesBot selects the right MCP tool, fetches live data from the DIP API, and returns a formatted answer.

Example questions:

• Fraktion split in WP 20?

• Who is Friedrich Merz?

• How many MdBs in WP 20?

Limitations

• Data accuracy — Fraktion distribution depends on the completeness of the DIP API data. The API may return slightly different counts than official Bundestag publications due to data propagation delays or membership changes mid-period.

• Person search — get_person_info and the chat command perform an in-memory substring match against display names. Politicians who left a Wahlperiode mid-term may appear with outdated Fraktion data.

• Groq rate limits — The free Groq tier has token-per-minute limits. Under heavy use the LLM calls may be throttled.

• MCP serve transport — The serve command uses stdio transport only. Network/SSE transport is not implemented.