{
  "markdown": "> 🇨🇭 **Part of the [Swiss Public Data MCP Portfolio](https://github.com/malkreide)**\n\n# ⚡ swiss-energy-mcp\n\n![Version](https://img.shields.io/badge/version-0.4.1-blue)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-purple)](https://modelcontextprotocol.io/)\n[![Data Source](https://img.shields.io/badge/Data-SFOE%20%2F%20GeoAdmin-red)](https://www.geo.admin.ch/)\n![Tests](https://img.shields.io/badge/tests-94%20passing-brightgreen)\n![CI](https://github.com/malkreide/swiss-energy-mcp/actions/workflows/ci.yml/badge.svg)\n\n> MCP server for Swiss energy data from the Federal Office of Energy (SFOE/BFE) via GeoAdmin REST API and opendata.swiss — no API key required.\n\n[🇩🇪 Deutsche Version](README.de.md)\n\n<p align=\"center\">\n  <img src=\"assets/demo.svg\" alt=\"swiss-energy-mcp demo – Claude asks for power plants near Wädenswil\" width=\"720\">\n</p>\n\n---\n\n## Overview\n\n`swiss-energy-mcp` gives AI assistants structured, location-based access to Switzerland's energy infrastructure. Built on open geodata from the Swiss Federal Office of Energy (SFOE/BFE) via the GeoAdmin REST API and the opendata.swiss catalogue — completely authentication-free.\n\nThe server is part of a growing portfolio of Swiss open data MCP servers. Think of it as the energy atlas counterpart to `swiss-road-mobility-mcp`: while the latter maps mobility, this server maps where Switzerland produces electricity, where solar potential exists, and which municipalities hold the \"Energiestadt\" label.\n\n**Anchor demo query:** *\"Which power plants are within 20 km of the school in Wädenswil — and is the municipality an Energiestadt?\"*\n\n---\n\n## Features\n\n- 🔍 **10 ready-to-use tools** covering all major energy data layers from SFOE/BFE\n- ⚡ **Power plants** — all types: photovoltaic, hydro, wind, biomass, nuclear, with optional category filter\n- 💨 **Wind turbines** — detailed data incl. manufacturer, model, hub height, annual production\n- 💧 **Hydropower plants** — type, status, turbine capacity, expected annual output\n- ☀️ **PV large installations** — project name, capacity, annual/winter production, altitude\n- 🌿 **Biogas plants** — plant name, output\n- 🏙️ **Energiestädte** — municipalities with the Swiss \"Energiestadt\" label (score, year awarded, audits)\n- 🏠 **Solar roof potential** — suitability category, area, orientation, and slope per roof segment\n- 📊 **Location energy profile** — combines 5 layers into a single overview for any Swiss location\n- 🗂️ **SFOE dataset search** — full-text search across SFOE publications on opendata.swiss\n- ✅ **Status check** — verifies availability of both upstream APIs\n- ☁️ **Dual transport** — stdio for Claude Desktop, Streamable HTTP for cloud deployment\n\n---\n\n## Prerequisites\n\n- Python 3.11+\n- [`uv`](https://github.com/astral-sh/uv) (recommended) or `pip`\n\n---\n\n## Installation\n\n### Claude Desktop (stdio transport)\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"swiss-energy-mcp\": {\n      \"command\": \"uvx\",\n      \"args\": [\"swiss-energy-mcp\"]\n    }\n  }\n}\n```\n\n**Config file locations:**\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n### Local development\n\n```bash\ngit clone https://github.com/malkreide/swiss-energy-mcp.git\ncd swiss-energy-mcp\nuv sync\nuv run swiss-energy-mcp\n```\n\n### Cloud / HTTP transport (Streamable HTTP)\n\nFor use via **claude.ai in the browser** (e.g. on managed workstations without local software):\n\n```bash\nSWISS_ENERGY_TRANSPORT=http uvx swiss-energy-mcp\n```\n\n> 💡 *\"stdio for the developer laptop, HTTP for the browser.\"*\n\n---\n\n## Quickstart\n\nOnce connected in Claude Desktop, try:\n\n```\nWhat power plants are within 20 km of Bern?\nShow me all wind turbines in the Jura region.\nIs Zürich an Energiestadt? What's their score?\nWhat is the solar potential of rooftops near lat=47.37, lon=8.54?\nGive me a full energy profile for the region around Lucerne.\nFind SFOE datasets about hydropower.\n```\n\n---\n\n## Available Tools\n\n| Tool | Description |\n|---|---|\n| `energy_find_power_plants` | All electricity generation plants within a radius (optional category filter) |\n| `energy_find_wind_turbines` | Wind turbines with manufacturer, model, hub height |\n| `energy_find_hydro_plants` | Hydropower plants with capacity and expected output |\n| `energy_find_pv_installations` | Large PV installations with annual/winter production |\n| `energy_find_biogas_plants` | Biogas plants |\n| `energy_find_energy_cities` | Municipalities with \"Energiestadt\" label |\n| `energy_solar_potential` | Solar suitability of roof segments at a location |\n| `energy_location_profile` | Combined energy profile (5 layers) for a location |\n| `energy_search_bfe_datasets` | Full-text search over SFOE datasets on opendata.swiss |\n| `energy_check_status` | Check availability of GeoAdmin and opendata.swiss APIs |\n\nAll tools accept WGS84 coordinates (lat/lon). Conversion to Swiss LV95 is handled internally.\n\n### Example Use Cases\n\n| Query | Tool |\n|---|---|\n| *\"Power plants near Bern (20 km radius)?\"* | `energy_find_power_plants` |\n| *\"Wind turbines in the Jura?\"* | `energy_find_wind_turbines` |\n| *\"Is Zürich an Energiestadt?\"* | `energy_find_energy_cities` |\n| *\"Solar potential of rooftops near lat=47.37, lon=8.54?\"* | `energy_solar_potential` |\n| *\"Full energy profile for Lucerne region?\"* | `energy_location_profile` |\n| *\"SFOE datasets on hydropower?\"* | `energy_search_bfe_datasets` |\n\n[→ More use cases by audience →](EXAMPLES.md)\n\n---\n\n## Data Sources\n\n| Source | URL | Auth |\n|---|---|---|\n| GeoAdmin REST API (swisstopo) | `api3.geo.admin.ch` | None |\n| opendata.swiss CKAN API | `opendata.swiss/api/3/action` | None |\n\n**BFE Layers used:**\n- `ch.bfe.elektrizitaetsproduktionsanlagen`\n- `ch.bfe.windenergieanlagen`\n- `ch.bfe.statistik-wasserkraftanlagen`\n- `ch.bfe.photovoltaik-grossanlagen`\n- `ch.bfe.biogasanlagen`\n- `ch.bfe.energiestaedte`\n- `ch.bfe.solarenergie-eignung-daecher`\n\n---\n\n## Configuration\n\nAll variables use the `SWISS_ENERGY_` prefix and are validated at startup.\n\n| Environment variable | Default | Description |\n|---|---|---|\n| `SWISS_ENERGY_TRANSPORT` | `stdio` | Transport mode: `stdio` or `http` |\n| `SWISS_ENERGY_HOST` | `127.0.0.1` | Host for HTTP transport. Bind `0.0.0.0` only inside a container. |\n| `SWISS_ENERGY_PORT` | `8000` | Port for HTTP transport |\n| `SWISS_ENERGY_CORS_ORIGINS` | `https://claude.ai` | Comma-separated allowed CORS origins (HTTP transport) |\n| `SWISS_ENERGY_ALLOWED_HOSTS` | *(empty)* | Comma-separated inbound `Host` allow-list. Only needed for a non-loopback bind. |\n| `SWISS_ENERGY_LOG_LEVEL` | `INFO` | Log level: `DEBUG` / `INFO` / `WARNING` / `ERROR` |\n| `SWISS_ENERGY_HTTP_TIMEOUT` | `20` | Upstream HTTP timeout in seconds |\n\nBoth list-valued variables also accept a JSON array — `[\"https://a.test\"]` —\nin addition to the comma-separated form.\n\nSee [`.env.example`](.env.example) for a template.\n\n---\n\n## MCP Protocol Version\n\nThis server speaks **two protocol eras** over the same endpoint. The client's\nfirst request on a connection decides which one applies; a later claim from the\nother era is refused.\n\n| Era | Revision | Who reaches it |\n|---|---|---|\n| `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. |\n| Per-request envelope | **`2026-07-28`** | A request carrying the `2026-07-28` `_meta` envelope opens a modern connection. |\n\nBoth revisions are pinned in\n[`tests/test_protocol_version.py`](tests/test_protocol_version.py) and asserted\nagainst the installed SDK, so a Dependabot bump of `mcp` cannot move either one\nsilently. The handshake ceiling is measured against a live `initialize` through\nthe assembled ASGI stack, not read off a constant name.\n\nNote that the SDK's `LATEST_PROTOCOL_VERSION` is an alias for the **modern**\nera, not for the handshake era — pinning against it alone would leave the era\nthat current clients actually negotiate free to drift.\n\n**Update policy.** When the gate fails, do not edit the constant blindly: read\nthe spec changelog between the two revisions, verify the server still behaves,\nthen move the constant, this section, `README.de.md` and\n[`CHANGELOG.md`](CHANGELOG.md) together.\n\n## MCP Primitives\n\nThe server uses all three MCP primitives:\n\n- **Tools** — 10 read-only tools (see above). Every search tool returns an\n  `EnergyResponse` envelope: structured `results` plus a Markdown `summary`,\n  explicit `source` / `license` attribution, and a `match_type` field.\n- **Resource** — `energy://layers`, the static catalogue of BFE GeoAdmin layers.\n- **Prompt** — `energy_site_assessment`, a guided location-analysis template.\n\n## Development Phase\n\nThe server is in **Phase 1 (read-only)**. See [docs/roadmap.md](docs/roadmap.md)\nfor the phased architecture and [docs/security.md](docs/security.md) for the\negress allow-list, SSRF protection and trifecta assessment.\n\n---\n\n## Safety & Limits\n\n| Aspect | Details |\n|--------|---------|\n| **Access** | Read-only (`readOnlyHint: true`) — the server cannot modify or delete any data |\n| **Personal data** | No personal data — all sources are aggregated, public infrastructure data |\n| **Rate limits** | Built-in per-query caps (max 50 search results, default 5 km radius) |\n| **Timeout** | 20 seconds per API call |\n| **Authentication** | No API keys required — both APIs are publicly accessible |\n| **Licenses** | All data under open licenses via [opendata.swiss](https://opendata.swiss/) (OGD) |\n| **Terms of Service** | Subject to ToS of the respective data sources: [GeoAdmin](https://www.geo.admin.ch/), [opendata.swiss](https://opendata.swiss/), [SFOE/BFE](https://www.bfe.admin.ch/) |\n\n---\n\n## Architecture\n\n```\n┌─────────────────┐     ┌───────────────────────────┐     ┌──────────────────────────┐\n│   Claude / AI   │────▶│   Swiss Energy MCP        │────▶│  SFOE / BFE Open Data    │\n│   (MCP Host)    │◀────│   (MCP Server)            │◀────│                          │\n└─────────────────┘     │                           │     │  GeoAdmin REST API       │\n                        │  10 Tools                 │     │  (api3.geo.admin.ch)     │\n                        │  Stdio | HTTP             │     │                          │\n                        │                           │     │  opendata.swiss CKAN     │\n                        │  server.py (FastMCP)      │     │  (opendata.swiss)        │\n                        │  api_client.py            │     └──────────────────────────┘\n                        │   LV95 conversion         │\n                        │   GeoAdmin queries        │\n                        └───────────────────────────┘\n```\n\n### Infrastructure Components\n\n| Component | Metaphor | Function |\n|---|---|---|\n| `api_client.py` | Switchboard | Handles HTTP requests, coordinate conversion, error handling |\n| LV95 converter | Translator | Converts WGS84 (lat/lon) to Swiss coordinate system |\n| `server.py` | Storefront | Exposes all 10 tools via FastMCP |\n\n---\n\n## Project Structure\n\n```\nswiss-energy-mcp/\n├── src/\n│   └── swiss_energy_mcp/\n│       ├── server.py          # FastMCP setup, lifespan, entry point\n│       ├── settings.py        # Typed configuration (pydantic-settings)\n│       ├── logging_config.py  # Structured JSON logging to stderr\n│       ├── api_client.py      # HTTP client, egress guard, LV95 conversion\n│       ├── models.py          # Pydantic input/output models\n│       ├── formatting.py      # Markdown summary builders\n│       ├── resources.py       # Layer-catalogue resource + prompt\n│       └── tools/             # One module per tool group\n│           ├── installations.py   # power, wind, hydro, PV, biogas\n│           ├── places.py          # solar, Energiestadt, location profile\n│           └── catalog.py         # dataset search, status\n├── tests/\n│   ├── test_unit.py         # Pure-unit tests (coords, formatting, egress)\n│   ├── test_tools.py        # Tool tests with respx-mocked APIs\n│   └── test_live.py         # Live integration tests (marked `live`)\n├── docs/                    # roadmap.md, security.md\n├── Dockerfile               # Multi-stage build, non-root user\n├── pyproject.toml\n├── CHANGELOG.md\n├── CONTRIBUTING.md          # Contribution guide (English)\n├── CONTRIBUTING.de.md       # Contribution guide (German)\n├── SECURITY.md              # Security policy (English)\n├── SECURITY.de.md           # Security policy (German)\n├── LICENSE\n├── README.md                # This file (English)\n└── README.de.md             # German version\n```\n\n---\n\n## Known Limitations\n\n- **GeoAdmin radius search:** Maximum search radius depends on layer density; very large radii may return partial results\n- **Solar potential:** Layer `ch.bfe.solarenergie-eignung-daecher` covers building footprints — not all roof types are classified\n- **Energiestadt:** Only municipalities with active label are included; historical entries may be incomplete\n- **opendata.swiss CKAN:** Full-text search covers metadata only, not document contents\n\n---\n\n## Testing\n\n```bash\n# Unit tests (no API key required)\nPYTHONPATH=src pytest tests/ -m \"not live\"\n\n# Live integration tests (network access required)\nPYTHONPATH=src pytest tests/ -m \"live\"\n```\n\n---\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md)\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) ([🇩🇪 Deutsch](CONTRIBUTING.de.md))\n\n---\n\n## Security\n\nSee [SECURITY.md](SECURITY.md) ([🇩🇪 Deutsch](SECURITY.de.md)) for the security\npolicy and posture summary, and [docs/security.md](docs/security.md) for the full\ntechnical security model.\n\n---\n\n## License\n\nMIT License — see [LICENSE](LICENSE)\n\n---\n\n## Author\n\nHayal Oezkan · [malkreide](https://github.com/malkreide)\n\n---\n\n## Credits & Related Projects\n\n- **Data:** [SFOE/BFE](https://www.bfe.admin.ch/) via [GeoAdmin](https://www.geo.admin.ch/) — Swiss Federal Office of Energy\n- **Data:** [opendata.swiss](https://opendata.swiss/) — Swiss Open Government Data portal\n- **Protocol:** [Model Context Protocol](https://modelcontextprotocol.io/) — Anthropic / Linux Foundation\n- **Related:** [swiss-road-mobility-mcp](https://github.com/malkreide/swiss-road-mobility-mcp) — MCP server for Swiss mobility data\n- **Related:** [zurich-opendata-mcp](https://github.com/malkreide/zurich-opendata-mcp) — MCP server for Zurich city open data\n- **Portfolio:** [Swiss Public Data MCP Portfolio](https://github.com/malkreide)\n\n<!-- mcp-name: io.github.malkreide/swiss-energy-mcp -->\n\n<!-- BEGIN GENERATED: install -->\n## Installation\n\nRun via [`uv`](https://docs.astral.sh/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`):\n\n```json\n{\n  \"mcpServers\": {\n    \"swiss-energy-mcp\": {\n      \"command\": \"uvx\",\n      \"args\": [\n        \"swiss-energy-mcp\"\n      ]\n    }\n  }\n}\n```\n<!-- END GENERATED: install -->\n",
  "bytes": 15241,
  "sha": "e946349d3e07a98ef25fd377889fe7efb142a9da08866b64afa279b6632a4fe6",
  "repo_slug": "malkreide/swiss-energy-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_malkreide_swiss_energy_mcp_7229e6ce/readme"
}