energy-mcp

Un servidor MCP para datos de demanda eléctrica y clima de EE. UU. Expone los datos como herramientas, recursos y avisos de MCP, se ejecuta localmente a través de stdio y funciona con cualquier cliente MCP: Claude Desktop, Claude Code, los adaptadores MCP de LangChain o el MCP Inspector.

Los datos se envían como un pequeño archivo SQLite de observaciones reales, por lo que puedes clonar el repositorio y ejecutarlo sin una base de datos ni una clave API.

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

¿Qué es MCP?

MCP es un protocolo abierto de Anthropic. Proporciona a un cliente de IA una forma estándar de llamar a herramientas externas y leer datos externos, en lugar de una integración personalizada por aplicación. Un servidor anuncia lo que ofrece, y un cliente se conecta y lo utiliza. Los servidores pueden ofrecer tres cosas:

• Herramientas: funciones que el modelo puede llamar.

• Recursos: contenido de solo lectura que el cliente carga como contexto.

• Avisos: plantillas reutilizables que un usuario puede elegir.

Este servidor proporciona las tres.

Related MCP server: euenergy-mcp

Herramientas, recursos y avisos

Herramientas:

• list_regions(): regiones disponibles, con recuentos de filas y cobertura de fechas.

• query_demand(region, start, end, limit=168): demanda horaria en MWh para un rango de fechas.

• daily_demand(region, start, end): promedio diario, pico y mínimo.

• peak_demand(region, start, end): la hora de mayor demanda.

• compare_regions(start, end, regions=None): promedio y pico entre regiones.

• demand_vs_weather(region, start, end): demanda diaria unida a la temperatura de esa región.

Recursos:

• schema://energy: una descripción simple de las tablas.

• docs://coverage: qué regiones y fechas están cargadas actualmente.

Avisos:

• analyze_demand(region): un iniciador que recorre una región a través de las herramientas.

Inicio rápido

Necesitas 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

Para explorar las herramientas en una interfaz de usuario, usa el MCP Inspector:

uv run mcp dev src/energy_mcp/server.py

Conéctalo a un cliente

Claude Desktop

Agrega esto a claude_desktop_config.json (en macOS, ~/Library/Application Support/Claude/claude_desktop_config.json) y reinicia Claude Desktop:

{
  "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

Luego pregunta en lenguaje natural, y el cliente elige las herramientas:

• "¿Qué red eléctrica de EE. UU. tuvo la mayor demanda promedio en julio de 2024?"

• "¿Cuándo alcanzó su punto máximo ERCOT en 2024 y qué calor hizo en Houston ese día?"

• "Compara la demanda de CISO y PJM para la primera semana de enero."

Ejemplo de salida

Resultados reales de los datos incluidos cuando un cliente llama a una herramienta:

> 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 es el interesante. La demanda de ERCOT aumenta con la temperatura de Houston en verano (carga de aire acondicionado), y la herramienta devuelve ambas series para que un modelo pueda señalar el enlace.

Datos

Todo es real, recortado al año calendario 2024 para mantener el archivo alrededor de 5 MB.

El archivo SQLite está incluido en el repositorio, por lo que no se obtiene nada en tiempo de ejecución. Para reconstruirlo o ampliar el rango de fechas (esto necesita una clave API de EIA gratuita):

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

Establece ENERGY_MCP_DB para apuntar el servidor a un archivo SQLite diferente.

Seguridad

• Solo lectura. La base de datos se abre con SQLite mode=ro, por lo que ninguna herramienta puede escribir.

• SQL parametrizado. Los argumentos se enlazan como parámetros, no se formatean en la cadena de consulta, por lo que no pueden inyectar SQL.

• Entradas validadas. Los argumentos de región y fecha se verifican antes de llegar a la base de datos, y una entrada incorrecta se devuelve como un error claro en el que el modelo puede actuar.

• Sin secretos para ejecutar. Los datos están en el repositorio; la clave de EIA es solo para reconstruirlos.

Desarrollo

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

Estructura:

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

El proyecto utiliza el SDK de MCP 1.x (la API FastMCP), que es lo que usan la documentación actual de Claude Desktop y la CLI mcp. El SDK 2.x es un rediseño más nuevo.

Relacionado

energy-text2sql es un agente de texto a SQL sobre los mismos datos de EIA y NOAA. Mismos datos, interfaz diferente: uno responde preguntas escribiendo SQL, este sirve los datos como herramientas MCP.

Licencia

MIT