gribs_mcp

MCP server for gribs.net — the Grünen-intern (party-internal), login-pflichtige KPV-Bayern platform hosting the Antragsbörse (Musteranträge, Beschlüsse, Positionspapiere) and secondary sections like Wissenswert, Mitgliederbriefe, and Mitgliederversammlungen.

This server exposes gribs.net content to AI harnesses (OpenCode) via the Model Context Protocol, giving an AI assistant read-only access to search and browse Antragsbörse posts and fetch the newest public posts. It is read-only by design — no writing, no triage, no uploads — and only surfaces content the running user is already authorized to see (login is handled via the user's own gribs.net credentials, cached locally).

Every politically relevant result carries a source URL and retrieval timestamp (Quellenpflicht) so downstream tools can cite where a claim came from and when it was fetched.

Tools

All tools are async, annotated readOnlyHint=True, and clamp limit parameters to [1, MAX]. Every result model carries url: str and retrieved_at: datetime (UTC).

Quellenpflicht: every tool that returns politically relevant data includes url + retrieved_at on each item. This is enforced at the Pydantic model layer, not by convention.

Related MCP server: mcp-moncompte

Library stack

No Playwright. gribs.net's simple form-POST login (no SSO, no JS handshake, no CSRF) does not require a browser — pure httpx is sufficient and dramatically simpler. There is no uv run playwright install step.

Setup

# 1. Install dependencies (uv manages a virtualenv automatically).
uv sync

# 2. Store your gribs.net credentials in the OS keyring.
#    This prompts for email + password via getpass (password is not echoed)
#    and optionally performs a test login to verify the credentials work.
uv run python -m gribs_mcp.auth

# 3. (Optional) Smoke-test the server over stdio.
uv run gribs-mcp

For CI / headless setups, fall back to environment variables (the keyring is checked first, then env vars):

export GRIBS_EMAIL="you@example.org"
export GRIBS_PASSWORD="…"

Cookies are cached in the OS keyring under service name gribs_mcp and are automatically refreshed when they expire (30-day TTL) or when the API returns 401/403. There is no browser profile to manage.

Configure in OpenCode

Register gribs-mcp as a stdio MCP server in your opencode.json (analog to allgaeuer_zeitung_mcp):

{
  "mcp": {
    "gribs_mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/gribs_mcp", "gribs-mcp"],
      "enabled": true
    }
  }
}

Replace /path/to/gribs_mcp with the absolute path to this checkout. The gribs-mcp script entry point is defined in pyproject.toml ([project.scripts]).

Development

uv sync                       # install dev deps
uv run ruff check             # lint (E/F/I/UP/B/SIM ruleset)
uv run ruff format --check    # format check
uv run mypy src/              # strict type check
uv run pytest                 # tests (deterministic, no live HTTP)

All four gates must pass before merging. Tests use HTML/JSON fixtures under tests/fixtures/ — no live gribs.net calls, so they run offline and deterministically.

Architecture

src/gribs_mcp/
├── __main__.py   # main() -> mcp.run(transport="stdio")
├── server.py     # FastMCP instance + 7 @mcp.tool definitions (read-only)
├── models.py     # Pydantic v2 models (frozen) with Quellenpflicht fields
├── client.py     # httpx.AsyncClient + cookie jar + auth retry (GribsClient)
├── parsers.py    # Pure HTML/JSON parsers (selectolax + trafilatura)
└── auth.py       # keyring credential + cookie cache (30-day TTL)

Key design decisions:

• httpx-only login — gribs.net uses a plain form-POST to /users/ajax_login with no SSO, no JS handshake, no CSRF token. A browser (Playwright) would be pure overhead. The client does a single httpx.AsyncClient.post and captures the Set-Cookie session cookie.

• Keyring cookie cache — credentials and session cookies are persisted in the OS keyring (service gribs_mcp), not on disk. A 30-day TTL plus per-cookie expires checks gate freshness; on 401/403 the client clears the cache and re-logs in (serialized by an asyncio.Lock to avoid concurrent-login races).

• JSON vs HTML response handling — gribs is inconsistent: /members/structure, /members/singlepost, and /members/expandStructure return JSON {error, ...} with HTML snippets inside; /members/search and /post/recentposts return raw HTML. The client has separate _post_form_json / _post_form_html paths sharing one retry helper.

• HTML-entity-encoded onclick args — the live structexp(...) calls in navigation HTML encode their object's quotes as ". Parsers call html.unescape() before parsing the JS object (shared _parse_js_object helper).

• Concurrent enrichment — recent_posts fetches the scaffold, then fires all postWidgetFill enrichment calls concurrently via asyncio.gather (3 parallel requests for the default 3 posts). Order is preserved (gather guarantees positional ordering).

• Read-only tools + Quellenpflicht — every tool is annotated readOnlyHint=True; every politically relevant output model carries url: str + retrieved_at: datetime (UTC) at the Pydantic schema level, so a missing source is a type error, not a convention violation.

Categories (live-verified)

The category parameter on search_antraege, list_categories, and list_antraege_in_category accepts these names:

Known limitations / roadmap

• list_antraege_in_category on leaf nodes returns an empty expansion — gribs.net's /members/expandStructure returns a search form (not post listings) when called on a leaf subcategory. To list posts in a subcategory, call search_antraege with the same l1/l2/l3 ids and a broad query (e.g. 'a' or 'der' — gribs doesn't support an empty searchstring).

• extract_downloads keyword heuristic — links are included if the URL ends in .pdf OR the anchor text contains a download keyword (download/pdf/antrag/vorlage/beschluss/musterantrag/herunterladen). This may produce false positives (e.g. a non-download link mentioning "antrag") or miss downloads with non-standard anchor text. The is_pdf flag distinguishes confirmed PDFs.

Reverse-engineering notes

Key facts about the gribs.net API (verified live 2026-07-18):

• Login: POST /users/ajax_login with email, password, keep=true. No SSO, no CSRF. Returns a 15-byte non-JSON status; success is signalled by Set-Cookie.

• API shape: all calls are POST application/x-www-form-urlencoded with header X-Requested-With: XMLHttpRequest. Responses are either JSON {error, ...} with HTML snippets inside (structure, singlepost, expandStructure) or raw HTML (search, recentposts).

• ID duality: posts have an internal post_id (needed by /members/singlepost) AND a WordPress wp-ID (returned by /members/search in ?wp=<id> deep-links), plus an optional ?h=<hash> share link. Use resolve_post_id to bridge wp_id → post_id.

• wp_id → post_id resolution: GET /?wp=<id> with follow_redirects=True returns the member page at /members/home/wp-<id>, which contains "post_id":"<N>" in a JSON-ish JS blob.

• Recent posts: /post/recentposts returns only scaffolds (post_id + spinner); the browser lazy-loads each teaser via /members/postWidgetFill with post_id + caller. The recent_posts tool does this concurrently.

License

MIT (placeholder pending final decision).