energy-mcp

Ein MCP-Server für US-Stromnachfrage- und Wetterdaten. Er stellt die Daten als MCP-Tools, -Ressourcen und -Prompts bereit, läuft lokal über stdio und arbeitet mit jedem MCP-Client: Claude Desktop, Claude Code, LangChain's MCP-Adapter oder dem MCP Inspector.

Die Daten werden als kleine SQLite-Datei mit echten Beobachtungen mitgeliefert, sodass Sie das Repo klonen und ohne Datenbank oder API-Schlüssel ausführen können.

Python 3.11+ · MCP SDK 1.x (FastMCP) · MIT

Was ist MCP

MCP ist ein offenes Protokoll von Anthropic. Es gibt einem KI-Client eine einheitliche Möglichkeit, externe Tools aufzurufen und externe Daten zu lesen, anstatt einer benutzerdefinierten Integration pro App. Ein Server gibt an, was er anbietet, und ein Client stellt eine Verbindung her und nutzt es. Server können drei Dinge anbieten:

• Tools: Funktionen, die das Modell aufrufen kann.

• Ressourcen: schreibgeschützte Inhalte, die der Client als Kontext lädt.

• Prompts: wiederverwendbare Vorlagen, die ein Benutzer auswählen kann.

Dieser Server bietet alle drei.

Related MCP server: euenergy-mcp

Tools, Ressourcen und Prompts

Tools:

• list_regions(): verfügbare Regionen mit Zeilenanzahlen und Datumsabdeckung.

• query_demand(region, start, end, limit=168): stündlicher Bedarf in MWh für einen Zeitraum.

• daily_demand(region, start, end): täglicher Durchschnitt, Spitze und Minimum.

• peak_demand(region, start, end): die einzelne Stunde mit dem höchsten Bedarf.

• compare_regions(start, end, regions=None): Durchschnitt und Spitze über Regionen hinweg.

• demand_vs_weather(region, start, end): täglicher Bedarf verknüpft mit der Temperatur dieser Region.

Ressourcen:

• schema://energy: eine einfache Beschreibung der Tabellen.

• docs://coverage: welche Regionen und Daten derzeit geladen sind.

Prompts:

• analyze_demand(region): ein Einstieg, der eine Region durch die Tools führt.

Schnellstart

Sie benötigen uv.

git clone https://github.com/visethchapman/energy-mcp
cd energy-mcp
uv run energy-mcp    # starts the server on stdio; it waits for a client

Um die Tools in einer Benutzeroberfläche zu erkunden, verwenden Sie den MCP Inspector:

uv run mcp dev src/energy_mcp/server.py

Mit einem Client verbinden

Claude Desktop

Fügen Sie dies zu claude_desktop_config.json hinzu (auf macOS, ~/Library/Application Support/Claude/claude_desktop_config.json) und starten Sie Claude Desktop neu:

{
  "mcpServers": {
    "energy": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/energy-mcp", "run", "energy-mcp"]
    }
  }
}

Claude Code

claude mcp add energy -- uv --directory /absolute/path/to/energy-mcp run energy-mcp

Dann fragen Sie in natürlicher Sprache, und der Client wählt die Tools aus:

• „Welches US-Stromnetz hatte im Juli 2024 die höchste durchschnittliche Nachfrage?“

• „Wann hatte ERCOT 2024 seinen Spitzenwert und wie heiß war es an diesem Tag in Houston?“

• „Vergleichen Sie die Nachfrage von CISO und PJM für die erste Januarwoche.“

Beispielausgabe

Echte Ergebnisse aus den gebündelten Daten, wenn ein Client ein Tool aufruft:

> peak_demand(region="ERCO", start="2024-01-01", end="2024-12-31")
{ "region": "ERCO", "period": "2024-08-20 23:00:00", "demand_mwh": 85544.0 }

> compare_regions(start="2024-07-01", end="2024-07-31")
[ {"region":"PJM",  "avg_mwh":109674.4, "peak_mwh":153121.0},
  {"region":"ERCO", "avg_mwh": 60200.6, "peak_mwh": 81200.0},
  {"region":"CISO", "avg_mwh": 32008.4, "peak_mwh": 44727.0},
  {"region":"NYIS", "avg_mwh": 21494.1, "peak_mwh": 28990.0} ]

> demand_vs_weather(region="ERCO", start="2024-07-01", end="2024-07-03")
[ {"day":"2024-07-01", "avg_mwh":67736.3, "tmax_c":37.8, "tmin_c":26.7},
  {"day":"2024-07-02", "avg_mwh":68463.9, "tmax_c":36.1, "tmin_c":27.2},
  {"day":"2024-07-03", "avg_mwh":68017.8, "tmax_c":34.4, "tmin_c":26.7} ]

demand_vs_weather ist das interessante. Die ERCOT-Nachfrage steigt mit der Houston- Temperatur im Sommer (Klimaanlagenlast), und das Tool gibt beide Reihen zurück, so dass ein Modell auf den Link verweisen kann.

Daten

Alles ist echt, auf das Kalenderjahr 2024 reduziert, um die Datei bei etwa 5 MB zu halten.

Die SQLite-Datei ist eingecheckt, sodass zur Laufzeit nichts abgerufen wird. Um sie neu zu erstellen oder den Datumsbereich zu erweitern (dafür ist ein kostenloser EIA-API-Schlüssel erforderlich):

uv run --extra build python scripts/build_sample_db.py --start 2023-01-01 --end 2024-12-31

Setzen Sie ENERGY_MCP_DB, um den Server auf eine andere SQLite-Datei zu verweisen.

Sicherheit

• Schreibgeschützt. Die Datenbank wird mit SQLite mode=ro geöffnet, sodass kein Tool schreiben kann.

• Parametrisiertes SQL. Argumente werden als Parameter gebunden, nicht in die Abfragezeichenfolge formatiert, sodass sie kein SQL einschleusen können.

• Validierte Eingaben. Regions- und Datumsargumente werden überprüft, bevor sie die Datenbank erreichen, und falsche Eingaben werden als klarer Fehler zurückgegeben, auf den das Modell reagieren kann.

• Keine Geheimnisse zum Ausführen. Die Daten befinden sich im Repository; der EIA-Schlüssel wird nur zum Neuerstellen benötigt.

Entwicklung

uv run pytest
uv run mcp dev src/energy_mcp/server.py

Layout:

src/energy_mcp/
  server.py                   # FastMCP server: tools, resources, prompts
  db.py                       # read-only SQLite access
  data/energy_sample.sqlite   # bundled real data
scripts/build_sample_db.py    # how the sample was assembled
tests/test_tools.py

Das Projekt verwendet das MCP 1.x SDK (die FastMCP-API), das auch die aktuellen Claude Desktop-Dokumentationen und die mcp-CLI verwenden. Das 2.x SDK ist ein neueres Redesign.

Verwandtes

energy-text2sql ist ein Text-zu-SQL-Agent über denselben EIA- und NOAA-Daten. Gleiche Daten, andere Schnittstelle: Einer beantwortet Fragen, indem er SQL schreibt, dieser stellt die Daten als MCP-Tools bereit.

Lizenz

MIT