swiss-energy-mcp

🇨🇭 属于 瑞士公共数据 MCP 组合

⚡ swiss-energy-mcp

通过 GeoAdmin REST API 和 opendata.swiss 获取瑞士联邦能源办公室（SFOE/BFE）的能源数据的 MCP 服务——无需 API 密钥。

🇩🇪 德语版

---

概述

swiss-energy-mcp 为 AI 助手提供对瑞士能源基础设施的结构化、基于位置的访问。它基于瑞士联邦能源办公室（SFOE/BFE）的开放地理数据，通过 GeoAdmin REST API 和 opendata.swiss 目录获取数据——完全无需身份验证。

该服务是不断扩大的瑞士开放数据 MCP 服务组合的一部分。可以把它看作 swiss-road-mobility-mcp 的能源图谱对应工具：后者绘制交通出行图谱，而本服务则展示瑞士的发电地点、太阳能潜力，以及哪些市镇获得了“Energiestadt”称号。

演示核心问题： “Wädenswil 的学校周边 20 公里内有哪些发电厂——该市镇是否获得了 Energiestadt 称号？”

---

功能

• 🔍 10 个开箱即用的工具，涵盖 SFOE/BFE 的所有主要能源数据图层
• ⚡ 发电厂——包括所有类型：光伏、水力、风力、生物质、核能，可选类别筛选
• 💨 风力涡轮机——详细数据，包括制造商、型号、轮毂高度和年发电量
• 💧 水电站——类型、状态、涡轮机容量、预期年发电量
• ☀️ 大型光伏设施——项目名称、容量、年发电量／冬季发电量、海拔
• 🌿 沼气厂——厂名、产能
• 🏙️ Energiestädte——获得瑞士“Energiestadt”称号的市镇（评分、授予年份、审核记录）
• 🏠 屋顶太阳能潜力——每个屋顶分区的适用类别、面积、朝向和坡度
• 📊 位置能源概况——整合 5 个图层，为瑞士境内任意地点生成单一概览
• 🗂️ SFOE 数据集搜索——在 opendata.swiss 上对 SFOE 出版物进行全文搜索
• ✅ 状态检查——验证两个上游 API 是否可用
• ☁️ 双重传输方式——stdio 用于 Claude Desktop，Streamable HTTP 用于云端部署

---

前置条件

• Python 3.11+
• uv（推荐）或 pip

---

安装

Claude Desktop（stdio 传输）

添加到 claude_desktop_config.json：

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

配置文件位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

本地开发

git clone https://github.com/malkreide/swiss-energy-mcp.git
cd swiss-energy-mcp
uv sync
uv run swiss-energy-mcp

云端／HTTP 传输（Streamable HTTP）

通过浏览器中的 claude.ai 使用（例如，在未安装本地软件的受管工作站上）：

SWISS_ENERGY_TRANSPORT=http uvx swiss-energy-mcp

💡 “开发者笔记本电脑用 stdio，浏览器用 HTTP。”

---

快速入门

连接到 Claude Desktop 后，试试：

What power plants are within 20 km of Bern?
Show me all wind turbines in the Jura region.
Is Zürich an Energiestadt? What's their score?
What is the solar potential of rooftops near lat=47.37, lon=8.54?
Give me a full energy profile for the region around Lucerne.
Find SFOE datasets about hydropower.

---

可用工具

工具	描述
energy_find_power_plants	查找指定半径内的所有发电厂（可选按类别筛选）
energy_find_wind_turbines	查找风力涡轮机及其制造商、型号和轮毂高度
energy_find_hydro_plants	查找水电站及其装机容量和预期发电量
energy_find_pv_installations	查找大型光伏设施及其年度／冬季发电量
energy_find_biogas_plants	查找沼气厂
energy_find_energy_cities	查找获得“Energiestadt”标签的市镇
energy_solar_potential	查询指定地点屋顶区块的太阳能适宜性
energy_location_profile	查询指定地点的综合能源概况（5 个图层）
energy_search_bfe_datasets	在 opendata.swiss 上全文搜索 SFOE 数据集
energy_check_status	检查 GeoAdmin 和 opendata.swiss API 是否可用

所有工具均接受 WGS84 坐标（纬度／经度）。坐标转换为瑞士 LV95 坐标由内部处理。

示例用例

查询	工具
“伯尔尼附近（半径 20 km）有哪些发电厂？”	energy_find_power_plants
“汝拉地区有哪些风力涡轮机？”	energy_find_wind_turbines
“苏黎世是 Energiestadt 吗？”	energy_find_energy_cities
“纬度=47.37、经度=8.54 附近屋顶的太阳能潜力如何？”	energy_solar_potential
“卢塞恩地区的完整能源概况？”	energy_location_profile
“有哪些关于水电的 SFOE 数据集？”	energy_search_bfe_datasets

→ 按受众分类的更多用例 →

---

数据来源

来源	URL	身份验证
GeoAdmin REST API（swisstopo）	api3.geo.admin.ch	无
opendata.swiss CKAN API	opendata.swiss/api/3/action	无

使用的 BFE 图层：

• ch.bfe.elektrizitaetsproduktionsanlagen
• ch.bfe.windenergieanlagen
• ch.bfe.statistik-wasserkraftanlagen
• ch.bfe.photovoltaik-grossanlagen
• ch.bfe.biogasanlagen
• ch.bfe.energiestaedte
• ch.bfe.solarenergie-eignung-daecher

---

配置

所有变量均使用 SWISS_ENERGY_ 前缀，并在启动时进行验证。

环境变量	默认值	描述
SWISS_ENERGY_TRANSPORT	stdio	传输模式：stdio 或 http
SWISS_ENERGY_HOST	127.0.0.1	HTTP 传输的主机。仅在容器内绑定 0.0.0.0。
SWISS_ENERGY_PORT	8000	HTTP 传输的端口
SWISS_ENERGY_CORS_ORIGINS	https://claude.ai	以逗号分隔的允许 CORS 来源（HTTP 传输）
SWISS_ENERGY_ALLOWED_HOSTS	(空)	以逗号分隔的入站 Host 允许列表。仅在绑定非回环地址时需要。
SWISS_ENERGY_LOG_LEVEL	INFO	日志级别：DEBUG / INFO / WARNING / ERROR
SWISS_ENERGY_HTTP_TIMEOUT	20	上游 HTTP 超时时间（秒）

两个列表类型的变量也接受 JSON 数组（如 ["https://a.test"]）， 也可使用逗号分隔的格式。

请参阅 .env.example 获取模板。

---

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 时无法在无提示的情况下更改任何一个版本。握手上限通过组装后的 ASGI 堆栈中的实时 initialize 请求测定，而不是从常量名称读取。

请注意，SDK 的 LATEST_PROTOCOL_VERSION 是现代时期的别名，而不是握手时期的别名——仅针对它固定版本，会导致当前客户端实际协商使用的时期可以悄然变更。

更新策略。 门禁检查失败时，不要盲目修改常量：请阅读两个修订版本之间的规范更新日志，确认服务仍能正常运行，然后一并更新常量、本节、README.de.md 和 CHANGELOG.md。

服务身份

每个现代时期的响应都会在 _meta["io.modelcontextprotocol/serverInfo"] 下携带服务身份；握手时期则在 initialize.serverInfo 中携带同一信息块一次：

{
  "name": "swiss_energy_mcp",
  "title": "Swiss Energy MCP",
  "version": "<version from the package metadata>",
  "websiteUrl": "https://github.com/malkreide/swiss-energy-mcp"
}

version 来自已安装软件包的元数据，绝不来自 src/ 中的字面值——scripts/check_version_sync.py 会拒绝其中手动维护的版本号。两个时期均通过组装后的 ASGI 堆栈进行测量，参见 tests/test_server_identity.py：SDK 的 version 默认值为空字符串，因此缺少构造函数参数时不会报错，而是悄然通过。

MCP 基元

此服务使用了全部三种 MCP 基元：

• 工具 — 10 个只读工具（见上文）。每个搜索工具都会返回一个 EnergyResponse 信封：包含结构化的 results 和 Markdown 格式的 summary、明确的 source / license 署名，以及 match_type 字段。
• 资源 — energy://layers，BFE GeoAdmin 图层的静态目录。
• 提示词 — energy_site_assessment，用于引导位置分析的模板。

开发阶段

此服务处于第 1 阶段（只读）。分阶段架构请参阅 docs/roadmap.md，出口允许列表、SSRF 防护和三要素评估请参阅 docs/security.md。

---

安全与限制

方面	详情
访问权限	只读（readOnlyHint: true）——服务无法修改或删除任何数据
个人数据	不涉及个人数据——所有来源均为汇总后的公共基础设施数据
速率限制	内置单次查询上限（最多 50 条搜索结果，默认半径 5 km）
超时	每次 API 调用 20 秒
身份验证	无需 API 密钥——两个 API 均可公开访问
许可证	所有数据均通过 opendata.swiss (OGD) 按开放许可证提供
服务条款	须遵守相应数据源的 ToS：GeoAdmin、opendata.swiss、SFOE/BFE

---

架构

┌─────────────────┐     ┌───────────────────────────┐     ┌──────────────────────────┐
│   Claude / AI   │────▶│   Swiss Energy MCP        │────▶│  SFOE / BFE Open Data    │
│   (MCP Host)    │◀────│   (MCP Server)            │◀────│                          │
└─────────────────┘     │                           │     │  GeoAdmin REST API       │
                        │  10 Tools                 │     │  (api3.geo.admin.ch)     │
                        │  Stdio | HTTP             │     │                          │
                        │                           │     │  opendata.swiss CKAN     │
                        │  server.py (FastMCP)      │     │  (opendata.swiss)        │
                        │  api_client.py            │     └──────────────────────────┘
                        │   LV95 conversion         │
                        │   GeoAdmin queries        │
                        └───────────────────────────┘

基础设施组件

组件	比喻	功能
api_client.py	配线板	处理 HTTP 请求、坐标转换和错误处理
LV95 转换器	翻译器	将 WGS84（纬度/经度）转换为瑞士坐标系
server.py	门店	通过 FastMCP 暴露全部 10 个工具

---

项目结构

swiss-energy-mcp/
├── src/
│   └── swiss_energy_mcp/
│       ├── server.py          # FastMCP setup, lifespan, entry point
│       ├── settings.py        # Typed configuration (pydantic-settings)
│       ├── logging_config.py  # Structured JSON logging to stderr
│       ├── api_client.py      # HTTP client, egress guard, LV95 conversion
│       ├── models.py          # Pydantic input/output models
│       ├── formatting.py      # Markdown summary builders
│       ├── resources.py       # Layer-catalogue resource + prompt
│       └── tools/             # One module per tool group
│           ├── installations.py   # power, wind, hydro, PV, biogas
│           ├── places.py          # solar, Energiestadt, location profile
│           └── catalog.py         # dataset search, status
├── tests/
│   ├── test_unit.py         # Pure-unit tests (coords, formatting, egress)
│   ├── test_tools.py        # Tool tests with respx-mocked APIs
│   └── test_live.py         # Live integration tests (marked `live`)
├── docs/                    # roadmap.md, security.md
├── Dockerfile               # Multi-stage build, non-root user
├── pyproject.toml
├── CHANGELOG.md
├── CONTRIBUTING.md          # Contribution guide (English)
├── CONTRIBUTING.de.md       # Contribution guide (German)
├── SECURITY.md              # Security policy (English)
├── SECURITY.de.md           # Security policy (German)
├── LICENSE
├── README.md                # This file (English)
└── README.de.md             # German version

---

已知限制

• GeoAdmin 半径搜索： 最大搜索半径取决于图层密度；半径过大时可能只返回部分结果
• 太阳能潜力： 图层 ch.bfe.solarenergie-eignung-daecher 覆盖建筑占地范围——并非所有屋顶类型都已分类
• Energiestadt： 仅包含拥有有效标签的市镇；历史条目可能不完整
• opendata.swiss CKAN： 全文搜索仅涵盖元数据，不包括文档内容

---

测试

# Unit tests (no API key required)
PYTHONPATH=src pytest tests/ -m "not live"

# Live integration tests (network access required)
PYTHONPATH=src pytest tests/ -m "live"

---

更新日志

参见 CHANGELOG.md

---

贡献

参见 CONTRIBUTING.md（🇩🇪 Deutsch）

---

安全

安全政策和安全状况摘要请参见 SECURITY.md（🇩🇪 Deutsch），完整的技术安全模型请参见 docs/security.md。

---

许可证

MIT License — 参见 LICENSE

---

作者

Hayal Oezkan · malkreide

---

致谢与相关项目

• 数据： SFOE/BFE，由 GeoAdmin 提供——瑞士联邦能源局
• 数据： opendata.swiss——瑞士开放政府数据门户
• 协议： Model Context Protocol——Anthropic / Linux Foundation
• 相关项目： swiss-road-mobility-mcp——用于瑞士交通数据的 MCP 服务
• 相关项目： zurich-opendata-mcp——用于苏黎世市开放数据的 MCP 服务
• 作品集： Swiss Public Data MCP Portfolio

安装

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

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