Skip to main content
Glama
lobbywatch-mcp

lobbywatch-mcp

by malkreide

πŸ›οΈ lobbywatch-mcp

CI PyPI version Python License: MIT Data: CC BY-SA 4.0 Swiss Public Data MCP Portfolio

An MCP server that connects AI models to Lobbywatch.ch, the largest lobby database of the Swiss Federal Parliament β€” conflicts of interest, lobby groups, access badges, and transparency scores.

πŸ‡©πŸ‡ͺ Deutsche Version

Part of the Swiss Public Data MCP Portfolio β€” connecting AI models to Swiss public data sources.


🎯 Anchor Demo Query

"Welche Mitglieder der WBK-N haben Interessenbindungen zu Bildungsverlagen oder privaten BildungstrΓ€gern, und wie ist ihre Transparenz-Bewertung?"

Which members of the National Council's Education Commission have declared conflicts of interest with educational publishers or private education providers, and how does their compensation transparency score compare?

β†’ More use cases by audience β†’

Demo

Demo: Claude using lobbywatch_search_parlamentarier_nach_branche and lobbywatch_get_transparenzquote


Related MCP server: parlament-mcp

Overview

Lobbywatch.ch maintains the largest public database on Swiss federal parliamentarians and their connections to lobby organisations: 245 parliamentarians, ~7'800 interessenbindungen (declared mandates), 139 lobby groups, 368 access-badge holders, updated weekly, licensed CC BY-SA 4.0.

lobbywatch-mcp exposes this data to Large Language Models via the Model Context Protocol. It is designed to be used alongside parlament-mcp (the official Swiss Parliament's Curia Vista data): the pair makes it possible to ask what a parliamentarian did officially and who they are connected to β€” in a single conversation.

Features

  • Dump-first, API-fallback architecture. The weekly JSON dump is the primary source (stable, verified in production); the live dataIF REST API is used only where it returns reliable data (lobby groups, search).

  • Stale-cache fallback, never silent. If the dump cannot be refreshed, a cached copy up to 7 days old answers instead, and every dump-backed response then carries a stale block with its download time, age and the reason the refresh failed. The source is retried every 15 minutes; lobbywatch_refresh_dump never falls back.

  • Seven Phase 1 tools β€” parliamentarian lookup, conflict-of-interest listing, branche search, lobby group fetch, rankings, transparency quota, cache control.

  • CC BY-SA 4.0 attribution baked into every response via Pydantic envelopes.

  • Dual transport β€” stdio for Claude Desktop, streamable-http / sse for cloud deployments.

  • Fuzzy name matching via rapidfuzz for natural LLM input like "Jositsch" or "Wehrli".

  • No authentication required (Phase 1 β€” No-Auth-First).

Architecture

                    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
   LLM client       β”‚     LobbywatchClient        β”‚
  (Claude Desktop,  β”‚                             β”‚
   Inspector, …)    β”‚   β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”     β”‚
        β”‚           β”‚   β”‚  Dump cache       β”‚     β”‚      cms.lobbywatch.ch
        β”‚  MCP      β”‚   β”‚  (24 h TTL,       β”‚     β”‚      β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
        β–Ό  stdio /  β”‚   β”‚   ~80 MB resident)β”œβ”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β–Ίβ”‚ weekly JSON      β”‚
   β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” HTTP β”‚   β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜     β”‚      β”‚ export (~17 MB)  β”‚
   β”‚ FastMCP │◄────►│                             β”‚      β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
   β”‚ server  β”‚      β”‚   β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”     β”‚      β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
   β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜      β”‚   β”‚  dataIF REST      β”œβ”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β–Ίβ”‚ /interface/v1/   β”‚
                    β”‚   β”‚  (live fallback)  β”‚     β”‚      β”‚   json/…         β”‚
                    β”‚   β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜     β”‚      β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Outbound HTTP runs through a single httpx.AsyncClient with follow_redirects=False, an SSRF guard that blocks RFC1918 / link-local / metadata IPs, and an httpx event hook that re-resolves on every request. The dump path is the primary source of truth for parliamentarian queries; dataIF is only used for lobby group lookups and the search endpoint.

Prerequisites

  • Python 3.11 or newer

  • Internet access to download the weekly Lobbywatch JSON export (~17 MB zipped)

Installation

From PyPI (after first release):

pip install lobbywatch-mcp

From source:

git clone https://github.com/malkreide/lobbywatch-mcp.git
cd lobbywatch-mcp
pip install -e ".[dev]"

Usage

Standalone

lobbywatch-mcp

This starts the server in stdio mode. For HTTP:

LOBBYWATCH_MCP_TRANSPORT=http LOBBYWATCH_MCP_PORT=8000 lobbywatch-mcp

Container

A hardened multi-stage Dockerfile ships with the repo (non-root, read-only-rootfs compatible). See docs/deployment.md and deploy/docker-compose.example.yml for resource limits, sticky-LB guidance and egress hardening.

docker build -t lobbywatch-mcp:0.2.0 .
docker run --rm -p 127.0.0.1:8000:8000 lobbywatch-mcp:0.2.0

Claude Desktop

Add to your claude_desktop_config.json:

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

A full example is provided in claude_desktop_config.json.

Example Queries

Once connected, try prompts such as:

  • "Give me the top 10 parliamentarians by number of interessenbindungen in the SP party."

  • "Which WBK-N members have mandates in the publishing or education industry?"

  • "Look up the lobby group 'economiesuisse' and list its connected parliamentarians."

  • "What is the compensation-transparency score distribution for the finance commission (FK-N)?"

Tools

All tool names use the lobbywatch_ namespace prefix (since 0.2.0) to avoid collisions with sibling portfolio servers.

Tool

Purpose

Source

lobbywatch_get_parlamentarier(name_or_id)

Full profile + all conflicts of interest

Dump

lobbywatch_list_interessenbindungen(name_or_id, nur_hauptberuflich, nur_aktiv)

Filtered mandate list

Dump

lobbywatch_search_parlamentarier_nach_branche(branche_query, kommission, limit)

Cross-filter by industry and commission

Dump

lobbywatch_get_lobbygruppe(name_or_id)

Lobby group with connected MPs and organisations

Live dataIF

lobbywatch_get_ranking(kriterium, kommission, partei, limit)

Top-N by criterion

Dump

lobbywatch_get_transparenzquote(kommission)

Distribution of compensation transparency labels

Dump

lobbywatch_refresh_dump() / lobbywatch_dump_status()

Cache control

Dump

Configuration

All behaviour is controlled via environment variables:

Variable

Default

Purpose

LOBBYWATCH_MCP_TRANSPORT

stdio

Transport (stdio, http, sse)

LOBBYWATCH_MCP_HOST

127.0.0.1

HTTP bind host (set to 0.0.0.0 only behind an auth gateway)

LOBBYWATCH_MCP_PORT

8000

HTTP bind port

LOBBYWATCH_MCP_CACHE_DIR

~/.cache/lobbywatch-mcp

Dump cache location

LOBBYWATCH_MCP_CACHE_TTL

86400 (24h)

Cache time-to-live in seconds

LOBBYWATCH_MCP_STALE_MAX_AGE

604800 (7 days)

Oldest cached dump that may answer when the refresh fails, in seconds; 0 disables the fallback

LOBBYWATCH_MCP_HTTP_TIMEOUT

60

HTTP timeout in seconds

LOBBYWATCH_MCP_CORS_ORIGINS

(unset)

Comma-separated origin allow-list for HTTP/SSE; when set, exposes Mcp-Session-Id to browsers

LOBBYWATCH_MCP_LOG_FORMAT

text

text (stdlib formatter) or json (structured via structlog)

LOBBYWATCH_MCP_LOG_LEVEL

INFO

DEBUG / INFO / WARNING / ERROR

LOBBYWATCH_MCP_OTEL_ENABLED

0

Set to 1 to enable OpenTelemetry tracing (requires pip install 'lobbywatch-mcp[obs]')

LOBBYWATCH_MCP_OTEL_ENDPOINT

(unset)

OTLP/HTTP collector endpoint (e.g. http://localhost:4318/v1/traces)

Project Structure

lobbywatch-mcp/
β”œβ”€β”€ src/lobbywatch_mcp/
β”‚   β”œβ”€β”€ __init__.py
β”‚   β”œβ”€β”€ __main__.py        # CLI + transport selection
β”‚   β”œβ”€β”€ config.py          # URLs, cache paths, attribution
β”‚   β”œβ”€β”€ client.py          # Dump download + dataIF client
β”‚   β”œβ”€β”€ models.py          # Pydantic v2 response envelopes
β”‚   └── server.py          # FastMCP tool registrations
β”œβ”€β”€ tests/
β”‚   β”œβ”€β”€ conftest.py        # Fixture parliamentarians
β”‚   β”œβ”€β”€ test_client.py     # Respx-mocked unit tests
β”‚   β”œβ”€β”€ test_server.py     # Tool integration tests
β”‚   └── test_live.py       # @pytest.mark.live β€” excluded from CI
β”œβ”€β”€ .github/workflows/
β”‚   β”œβ”€β”€ ci.yml             # Test matrix + ruff
β”‚   └── publish.yml        # PyPI OIDC Trusted Publisher
β”œβ”€β”€ claude_desktop_config.json
β”œβ”€β”€ pyproject.toml
└── ...

Data License & Attribution

The code is released under the MIT License.

The data served through this MCP is Β© Lobbywatch.ch and licensed under CC BY-SA 4.0. Every response envelope includes the attribution string. Downstream users must:

  1. Credit Lobbywatch.ch as the data source.

  2. Share derivative datasets under the same CC BY-SA 4.0 terms.

  3. Understand that Lobbywatch is a community-researched database β€” not an official register. It is authoritative for transparency research but should not be confused with the Federal Parliament's own declarations.

Known Limitations

  • The upstream /table/parlamentarier/... dataIF REST endpoint currently returns empty result sets. The server works around this by using the weekly JSON dump instead.

  • zutrittsberechtigungen (access badges) are not populated in the "essential" dump variant used here. A future release will add a dedicated tool using the non-essential dump.

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md for the security posture, accepted-risk decisions, and how to report a vulnerability.

MCP Protocol Version

This server speaks two protocol eras over the same endpoint. The client's first request on a connection decides which one applies; a later claim from the other era is refused.

Era

Revision

Who reaches it

initialize handshake

2024-11-05 … 2025-11-25

What today's clients speak. The server answers with the revision asked for, or with the 2025-11-25 ceiling when the request asks for something newer.

Per-request envelope

2026-07-28

A request carrying the 2026-07-28 _meta envelope opens a modern connection.

Both revisions are pinned in tests/test_protocol_version.py and asserted against the installed SDK, so a Dependabot bump of mcp cannot move either one silently. The constants alone are the weaker form, so tests/test_spec_2026_07_28.py measures both eras through the assembled ASGI app: server/discover without a session, an initialize asking for a future revision capped at 2025-11-25, and every tool called over a 2026-07-28 connection with SDK deprecations raised as errors.

Native to 2026-07-28. lobbywatch_refresh_dump reports its progress as notifications/progress, which both eras deliver to any client that sends a progressToken. It used to log via notifications/message; logging is deprecated in 2026-07-28 (SEP-2577) and only delivered on requests that opt in with a log level, so modern clients silently received nothing. serverInfo now carries the package version β€” under 2026-07-28 it is stamped into the _meta of every response.

Note that the SDK's LATEST_PROTOCOL_VERSION is an alias for the modern era, not for the handshake era β€” pinning against it alone would leave the era that current clients actually negotiate free to drift.

Update policy. When the gate fails, do not edit the constant blindly: read the spec changelog between the two revisions, verify the server still behaves, then move the constant, this section, README.de.md and CHANGELOG.md together.

Changelog

See CHANGELOG.md.

License

MIT License β€” see LICENSE. Data CC BY-SA 4.0 β€” see NOTICE.md.

Author

malkreide Β· GitHub


Part of the Swiss Public Data MCP Portfolio.

Installation

Run via uv's uvx β€” no clone or manual install needed. Add to your MCP client config (mcpServers for Claude Desktop, Cursor and Windsurf; use a top-level servers key for VS Code in .vscode/mcp.json):

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

Available Tools

8 tools
lobbywatch_dump_statusA
Read-onlyIdempotent

Return current dump cache status without forcing a refresh.

Use cases: - "How fresh is the cached data right now?" - "When was the dump last loaded?"

Inputs: no named parameters. Returns: stale, loaded, source, cached_at, +3 more

lobbywatch_get_lobbygruppeA
Read-onlyIdempotent

Fetch a lobby group (interessengruppe) from the live Lobbywatch dataIF, including its connected organisations and parliamentarians.

Uses the live REST API since this endpoint returns fresh data.

Use cases: - "Look up 'economiesuisse' and list connected MPs" - "Who's affiliated with the lobby group #42?" - "Show me all parliamentarians linked to the pharma lobby"

Inputs: name_or_id (required). Returns: source, provenance, lobbygruppe

lobbywatch_get_parlamentarierA
Read-onlyIdempotent

Look up a Swiss federal parliamentarian and return their full profile, including all declared/researched interessenbindungen.

On a fuzzy miss, the response surfaces near-miss candidates so the LLM can prompt the user with "did you mean…?" suggestions instead of treating the empty result as authoritative (audit ARCH-003).

Args: name_or_id: Either the numeric Lobbywatch ID (as string) or a name. Name matching is fuzzy β€” partial last names work.

Use cases: - "Show me Anna Mustermann's full lobbying profile" - "What conflicts of interest does parliamentarian #42 declare?" - "Look up Wehrli β€” give me everything you have"

Inputs: name_or_id (required). Returns: stale, source, provenance, suggestions, +1 more

lobbywatch_get_rankingA
Read-onlyIdempotent

Rank parliamentarians by a criterion.

Args: kriterium: One of "anzahl_interessenbindungen", "anzahl_hauptberuflich". kommission: Optional commission abbreviation filter (e.g. "WBK-N"). partei: Optional party filter (e.g. "SP", "SVP", "Mitte"). limit: Top-N to return (1–100).

Use cases: - "Top 10 SP MPs by total mandate count" - "Which Mitte-Fraktion members have the most full-time mandates?" - "Rank WBK-N by IB count β€” who's most involved?"

Inputs: limit, partei, kriterium, kommission. Returns: stale, source, eintraege, kriterium, +1 more

lobbywatch_get_transparenzquoteA
Read-onlyIdempotent

Aggregate the verguetungstransparenz_beurteilung values across all parliamentarians (or a commission subset) and return the distribution.

Useful to answer: 'How transparent is the education commission on compensation disclosure?'

Use cases: - "How transparent is the FK-N on compensation disclosure?" - "Distribution of transparency labels across the whole parliament" - "Compare WBK-N transparency vs the council average"

Inputs: kommission. Returns: scope, stale, total, source, +3 more

lobbywatch_list_interessenbindungenA
Read-onlyIdempotent

Return the list of interessenbindungen (conflicts of interest) for one parliamentarian, optionally restricted to full-time or currently-active mandates.

On a fuzzy miss, near-miss candidates are returned in suggestions (audit ARCH-003).

Args: name_or_id: ID or name (fuzzy). nur_hauptberuflich: If True, only main-occupation mandates. nur_aktiv: If True, drop mandates with an end date (bis) set.

Use cases: - "Which active mandates does Jositsch hold today?" - "List Anna Mustermann's full-time mandates only" - "Give me every IB ever declared by parliamentarian #1"

Inputs: name_or_id (required), nur_aktiv, nur_hauptberuflich. Returns: count, stale, source, provenance, +3 more

lobbywatch_refresh_dumpA
Idempotent

Force re-download of the weekly Lobbywatch dump. Returns the new cache status.

Reports progress via the MCP Context (audit SDK-003) so long-running downloads (~17 MB compressed) surface useful feedback to the calling LLM and operator.

Use cases: - "Force a fresh download β€” the data looks stale" - "I just heard about a new declaration β€” refresh and re-check"

Inputs: no named parameters. Returns: stale, loaded, source, cached_at, +3 more

lobbywatch_search_parlamentarier_nach_brancheA
Read-onlyIdempotent

Find parliamentarians with interessenbindungen matching a search term against the linked organisation's name, alias, and (when available) branche field. Optional commission filter.

Note: the Lobbywatch "essential" dump does not embed a branche taxonomy on each organisation β€” branche is referenced by id and resolved via the separate interessengruppe table. Version 0.1 therefore performs a substring match against organisation names and the branche field when present. Version 0.2 will add full cross-reference resolution.

Args: branche_query: Substring match (case-insensitive) against organisation.anzeige_name, organisation.name, organisation.branche (where present), e.g. "Verlag", "Pharma", "Bank", "Krankenkasse", "Bildung". kommission: Commission abbreviation to restrict the result to, e.g. "WBK-N" for the education commission of the National Council. limit: Max number of {parlamentarier, ib} pairs returned (1–200).

Use cases: - "Which WBK-N members hold mandates in the publishing industry?" - "Cross-filter Pharma Γ— FK-N to surface health-policy lobbyists" - "List every parliamentarian with a 'Krankenkasse' connection"

Inputs: branche_query (required), limit, kommission. Returns: count, query, stale, source, +2 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 8 tools

    Disambiguation4/5

    Most tools target clearly distinct actions (lookup, industry search, ranking, transparency, lobby group, cache ops). However, get_parlamentarier returns the full profile including interessenbindungen, which overlaps with list_interessenbindungen; the descriptions clarify that the latter adds filtering, so the boundary is workable but not perfectly sharp.

    Naming Consistency5/5

    All tools share the lobbywatch_ prefix and use snake_case with a mostly verb_noun pattern (get_parlamentarier, list_interessenbindungen, get_ranking, refresh_dump). dump_status is a minor noun-only deviation but still fully consistent in style.

    Tool Count5/5

    Eight tools is well-scoped for a domain-specific lobbying data server. Each tool earns its place, including the two cache-management tools that are justified by the dump-backed architecture.

    Completeness4/5

    The surface covers lookup, IB listing, industry/commission cross-filtering, rankings, transparency aggregates, lobby groups, and cache lifecycle. Minor gaps exist: no direct organisation or commission listing, and branche search is only a substring match pending v0.2, but core workflows are covered.

    Maintenance

    ActivitySlowing
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      An MCP server connecting AI models to the Swiss Federal Parliament via the Curia Vista OData API, enabling queries of motions, votes, members, sessions, and debate transcripts without authentication.
      7
      54 PyPI
      2
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      An MCP server for Swiss Federal Railways (SBB) open data, enabling AI models to query real-time disruptions, passenger frequencies, station details, and more without an API key.
      9
      26 PyPI
      2
      MIT