sens-mcp

Ein MCP-Server (Model Context Protocol) und Entwickler-Starter-Kit für die SENS Energy Data API — die polnische Strommarktdaten-API (Verteilernetzbetreiber, Tarife und zusammengesetzte Preisberechnungen).

Er löst das „Cold-Start“-Problem für LLMs und KI-Agenten (Claude Desktop, Cursor, LangChain, n8n, ...), die mit der API sprechen: Der polnische Energiemarkt hat ein eigenes Vokabular (OSD vs. sprzedawca, Tarifgruppen G11/G12/G12w/...), das Modelle nicht von Haus aus kennen, und rohe REST-Antworten sind zu groß und zu leicht, um sie von Hand nachzurechnen.

sens-mcp bietet:

• Zero-Shot-Discoverability — eine MCP-Ressource (sens://market/cheat-sheet) und Discovery-Tools (resolve_operator, search_tariffs), die dem Modell das Marktvokabular in weniger als ~400 Tokens beibringen.

• Actionable Self-Correction — Tool-Fehler liefern strukturiertes JSON mit Vorschlägen (did you mean G12w?) statt roher HTTP-Fehler, sodass ein Agent in einer ReAct-Schleife seinen nächsten Aufruf selbst korrigieren kann.

• Single-Source-of-Truth-Berechnungen — alle Preis-/Mengenberechnungen finden im SENS-Backend statt; das Toolkit berechnet keine Gesamtsummen clientseitig neu.

• Nicht-blockierender Start — der Server startet sofort mit einem eingebetteten Fallback-Marktschema; Live-Tarifmetadaten werden im Hintergrund aktualisiert.

Schnellstart

Ausführen mit uvx (empfohlen, kein Installationsschritt)

export SENS_API_KEY=sens_live_your_key_here
uvx sens-mcp

Oder mit pip installieren

pip install sens-mcp
export SENS_API_KEY=sens_live_your_key_here
python -m sens_mcp

Umgebungsvariablen

Related MCP server: US ISO Grid MCP

Verwendung mit einem KI-Agenten

Claude Desktop

Fügen Sie die folgende Konfiguration zu claude_desktop_config.json hinzu (siehe configs/claude_desktop_config.json):

{
  "mcpServers": {
    "sens-energy": {
      "command": "uvx",
      "args": ["sens-mcp"],
      "env": {
        "SENS_API_KEY": "sens_live_your_key_here"
      }
    }
  }
}

Cursor

Fügen Sie die Konfiguration zu .cursor/mcp.json hinzu (siehe configs/cursor_mcp.json) — gleiche Struktur wie oben.

Verfügbare Tools

Ressource: sens://market/cheat-sheet — ein Markdown-Spickzettel zum Vokabular des polnischen Strommarkts (Verteilnetzbetreiber, Tarifgruppen, Preisbestandteile).

Entwicklerbeispiele (kein MCP erforderlich)

Selbst enthaltene Beispiele, die die SENS-REST-API direkt aufrufen:

• examples/python/get_prices.py

• examples/python/list_tariffs.py

• examples/python/async_stream.py — Deltasynchronisierung über since

• examples/typescript/get_prices.ts

• examples/curl/api_requests.sh

API-Referenz (Grundlagen)

• Basis-URL: https://api.getsens.energy

• Authentifizierung: X-API-KEY: <Ihr Key>-Header (kein Bearer, kein Query-Parameter).

• GET /api/v1/prices — osd, sprzedawca, taryfa, market, date, annual_kwh, region, since, page, size (max. 1000).

• GET /api/v1/tariffs — since/If-Modified-Since für Datenabgleiche, page, size.

• GET /api/v1/tariffs/components?tariff_id=... — Preisbestandteil eines einzelnen Tarifs, unterstützt ebenfalls since.

Vollständige Swagger/OpenAPI-Dokumentation: https://api.getsens.energy/api/docs. Dossierende Entwicklerdokumentation (Schnellstart, MCP-Integrationsanleitung, Marktvokabular): docs.getsens.energy.

Entwicklung

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest

Tests mocken alle HTTP-Aufrufe mit respx — nichts in der Standard-Testsuite greift die Live-API an.

Live-Integrationstests (opt-in)

tests/test_live_integration.py startet den echten Server als Subprozess über das echte MCP-stdio-Protokoll gegen die echte SENS-Produktions-API und prüft die Byte-für-Byte-Übereinstimmung zwischen MCP-Tool-Antworten und rohen httpx-Aufrufen an denselben Endpunkten. Ist standardmäßig deaktiviert; nur mit einem echten Key explizit ausführen:

SENS_API_KEY=<a real key> pytest -m live tests/test_live_integration.py -v

Lizenz

MIT