lobbywatch-mcp

🏛️ lobbywatch-mcp

一个将 AI 模型连接到 Lobbywatch.ch 的 MCP 服务。Lobbywatch.ch 是瑞士联邦议会最大的游说数据库，涵盖利益冲突、游说团体、门禁证和透明度评分。

🇩🇪 德语版

属于 瑞士公共数据 MCP 项目集，致力于将 AI 模型连接到瑞士公共数据源。

---

🎯 锚点演示查询

“哪些国家委员会教育、科学与文化委员会（WBK-N）成员申报了与教育出版商或私人教育机构相关的利益关系？他们的透明度评分如何？”

国民院教育委员会有哪些成员申报了与教育出版商或私人教育机构相关的利益冲突？他们的报酬透明度评分相比如何？

→ 按受众查看更多用例 →

演示

---

概述

Lobbywatch.ch 维护着规模最大的瑞士联邦议员及其与游说组织关系的公共数据库：245 名议员、约 7,800 项利益关系（申报的职务）、139 个游说团体、368 名门禁证持有人；每周更新，采用 CC BY-SA 4.0 许可。

lobbywatch-mcp 通过 Model Context Protocol 向大语言模型提供这些数据。它旨在与 parlament-mcp 配合使用，后者提供瑞士联邦议会官方的 Curia Vista 数据；两者结合后，用户可以在一次对话中询问议员正式做过什么，以及他们与谁有关联。

功能

• 优先使用数据转储，API 作为备用。 每周 JSON 转储是主要数据源（稳定，已在生产环境中验证）；仅在实时 dataIF REST API 能可靠返回数据时才使用该 API（游说团体、搜索）。
• 缓存过期时使用备用数据，绝不静默处理。 如果无法刷新转储，则使用最多 7 天前的缓存副本作答；随后每个由转储支持的响应都会包含一个 stale 区块，记录下载时间、数据年龄和刷新失败原因。每 15 分钟重试一次数据源；lobbywatch_refresh_dump 绝不会使用备用数据。
• Phase 1 提供七种工具——议员查询、利益冲突列表、行业搜索、游说团体获取、排名、透明度比例、缓存控制。
• 通过 Pydantic 封装对象在每个响应中加入 CC BY-SA 4.0 归属信息。
• 双传输方式——stdio 适用于 Claude Desktop，streamable-http / sse 适用于云端部署。
• 通过 rapidfuzz 模糊匹配姓名，支持“Jositsch”或“Wehrli”等自然语言输入。
• 无需身份验证（Phase 1——优先免认证）。

架构

                    ┌─────────────────────────────┐
   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/…         │
                    │   └───────────────────┘     │      └──────────────────┘
                    └─────────────────────────────┘

出站 HTTP 请求通过单个 httpx.AsyncClient 发起，并设置 follow_redirects=False；其中包含可阻止 RFC1918、链路本地和元数据 IP 的 SSRF 防护，以及一个会在每次请求时重新解析地址的 httpx 事件钩子。议员查询以数据转储为主要事实来源；dataIF 仅用于游说团体查询和搜索端点。

前置条件

• Python 3.11 或更高版本
• 可访问互联网，以便下载每周更新的 Lobbywatch JSON 导出文件（压缩后约 17 MB）

安装

从 PyPI 安装（首次发布后）：

pip install lobbywatch-mcp

从源代码安装：

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

使用方法

独立运行

lobbywatch-mcp

这会以 stdio 模式启动服务。使用 HTTP：

LOBBYWATCH_MCP_TRANSPORT=http LOBBYWATCH_MCP_PORT=8000 lobbywatch-mcp

容器

仓库附带一个经过加固的多阶段 Dockerfile（以非 root 用户运行，兼容只读根文件系统）。有关资源限制、粘性负载均衡指南和出站流量加固，请参阅 docs/deployment.md 和 deploy/docker-compose.example.yml。

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

将以下内容添加到你的 claude_desktop_config.json：

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

claude_desktop_config.json 中提供了完整示例。

示例查询

连接后，可以尝试以下提示词：

• “列出 SP 党按 Interessenbindungen 数量排名前 10 的议员。”
• “哪些 WBK-N 成员在出版或教育行业拥有委任？”
• “查找游说团体 ‘economiesuisse’，并列出与其有关联的议员。”
• “财政委员会（FK-N）的薪酬透明度评分分布如何？”

工具

所有工具名称都使用 lobbywatch_ 命名空间前缀（自 0.2.0 起），以避免与同系列的其他服务发生冲突。

工具	用途	来源
lobbywatch_get_parlamentarier(name_or_id)	完整个人资料及所有利益冲突	转储
lobbywatch_list_interessenbindungen(name_or_id, nur_hauptberuflich, nur_aktiv)	筛选后的委任列表	转储
lobbywatch_search_parlamentarier_nach_branche(branche_query, kommission, limit)	按行业和委员会交叉筛选	转储
lobbywatch_get_lobbygruppe(name_or_id)	游说团体及其关联议员和组织	实时数据IF
lobbywatch_get_ranking(kriterium, kommission, partei, limit)	按标准列出前 N 名	转储
lobbywatch_get_transparenzquote(kommission)	薪酬透明度标签的分布	转储
lobbywatch_refresh_dump() / lobbywatch_dump_status()	缓存控制	转储

配置

所有行为均通过环境变量控制：

变量	默认值	用途
LOBBYWATCH_MCP_TRANSPORT	stdio	传输方式（stdio、http、sse）
LOBBYWATCH_MCP_HOST	127.0.0.1	HTTP 绑定主机（仅在认证网关之后时设为 0.0.0.0）
LOBBYWATCH_MCP_PORT	8000	HTTP 绑定端口
LOBBYWATCH_MCP_CACHE_DIR	~/.cache/lobbywatch-mcp	转储缓存位置
LOBBYWATCH_MCP_CACHE_TTL	86400 (24h)	缓存生存时间（秒）
LOBBYWATCH_MCP_STALE_MAX_AGE	604800 (7 days)	刷新失败时可用于响应的最旧缓存转储，单位为秒；0 表示禁用回退
LOBBYWATCH_MCP_HTTP_TIMEOUT	60	HTTP 超时时间（秒）
LOBBYWATCH_MCP_CORS_ORIGINS	(未设置)	HTTP/SSE 的逗号分隔来源允许列表；设置后会向浏览器公开 Mcp-Session-Id
LOBBYWATCH_MCP_LOG_FORMAT	text	text（stdlib 格式化器）或 json（通过 structlog 生成结构化日志）
LOBBYWATCH_MCP_LOG_LEVEL	INFO	DEBUG / INFO / WARNING / ERROR
LOBBYWATCH_MCP_OTEL_ENABLED	0	设为 1 以启用 OpenTelemetry 跟踪（需要 pip install 'lobbywatch-mcp[obs]'）
LOBBYWATCH_MCP_OTEL_ENDPOINT	(未设置)	OTLP/HTTP 收集器端点（例如 http://localhost:4318/v1/traces）

项目结构

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
└── ...

数据许可与署名

代码采用 MIT 许可证发布。

数据通过此 MCP 提供，版权归 Lobbywatch.ch 所有，并依据 CC BY-SA 4.0 授权。每个响应信封都包含署名字符串。下游用户必须：

1. 注明 Lobbywatch.ch 为数据来源。
2. 根据相同的 CC BY-SA 4.0 条款分享衍生数据集。
3. 了解 Lobbywatch 是一个由社区调研维护的数据库，并非官方登记册。它适用于透明度研究，但不应与联邦议会自己的申报记录混淆。

已知限制

• 上游 /table/parlamentarier/... dataIF REST 端点目前返回空结果集。服务通过改用每周 JSON 转储来绕过这一问题。
• 此处使用的「essential」转储变体中没有填充 zutrittsberechtigungen（通行证）。未来版本会使用 non-essential 转储添加专用工具。

贡献

请参阅 CONTRIBUTING.md。

安全

请参阅 SECURITY.md，了解安全状况、接受风险的决策，以及如何报告漏洞。

MCP 协议版本

此服务通过同一个端点支持两个协议时代。客户端在连接上的第一个请求决定适用的协议；之后若声明另一个时代，则会被拒绝。

时代	修订版本	适用对象
initialize 握手	2024-11-05 … 2025-11-25	当前客户端使用的协议。服务会返回请求指定的修订版本；若请求的是更新版本，则返回上限 2025-11-25。
每请求信封	2026-07-28	携带 2026-07-28 _meta 信封的请求会建立现代连接。

两个修订版本都在 tests/test_protocol_version.py 中固定，并与已安装的 SDK 进行断言，因此 Dependabot 更新 mcp 时不会悄然变动其中任何一个。仅固定常量的保障较弱，因此 tests/test_spec_2026_07_28.py 会通过组装后的 ASGI 应用测试两个时代：无会话时的 server/discover、将未来修订版本请求限制为 2025-11-25 的 initialize，以及通过 2026-07-28 连接调用的所有工具（SDK 弃用警告会作为错误处理）。

2026-07-28 原生支持。 lobbywatch_refresh_dump 通过 notifications/progress 报告进度；两个时代都会将其发送给任何提供 progressToken 的客户端。它过去通过 notifications/message 记录日志；在 2026-07-28 中，日志记录已弃用（SEP-2577），且只会发送给选择了日志级别的请求，因此现代客户端会静默地收不到任何内容。现在 serverInfo 会携带软件包版本——在 2026-07-28 下，该版本会写入每个响应的 _meta。

请注意，SDK 的 LATEST_PROTOCOL_VERSION 是现代时代的别名，而不是握手时代的别名——仅以它为基准固定版本，会导致当前客户端实际协商的时代仍可能发生变动。

更新政策。 若检查未通过，不要盲目修改常量：阅读两个修订版本之间的规范变更日志，确认服务仍能正常运行，然后一并更新常量、本节、README.de.md 和 CHANGELOG.md。

更新日志

请参阅 CHANGELOG.md。

许可证

MIT License——请参阅 LICENSE。数据采用 CC BY-SA 4.0 许可——请参阅 NOTICE.md。

作者

malkreide · GitHub

---

瑞士公共数据 MCP 作品集的一部分。

安装

通过 uv 的 uvx 运行——无需克隆或手动安装。添加到 MCP 客户端配置中（Claude Desktop、Cursor 和 Windsurf 使用 mcpServers；VS Code 在 .vscode/mcp.json 中使用顶层 servers 键）：

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