energy-mcp

一个提供美国电力需求和天气数据的MCP服务器。它将数据以MCP工具、资源和提示词的形式暴露出来，通过stdio本地运行，并支持任何MCP客户端：Claude Desktop、Claude Code、LangChain的MCP适配器或MCP Inspector。

数据以一个包含真实观测数据的小型SQLite文件形式提供，因此你可以克隆仓库并直接运行，无需数据库或API密钥。

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

什么是MCP

MCP是Anthropic提出的一个开放协议。它为AI客户端提供了一种标准方式来调用外部工具和读取外部数据，而不是为每个应用进行自定义集成。服务器声明其提供的内容，客户端连接并使用它。服务器可以提供三类内容：

• 工具：模型可以调用的函数。

• 资源：客户端加载作为上下文的只读内容。

• 提示词：用户可以选择的可重用模板。

此服务器提供了以上全部三类内容。

Related MCP server: euenergy-mcp

工具、资源和提示词

工具：

• list_regions()：可用的区域，包含行数和日期覆盖范围。

• query_demand(region, start, end, limit=168)：某个日期范围内按小时统计的电力需求（单位：MWh）。

• daily_demand(region, start, end)：日均、峰值和最低需求。

• peak_demand(region, start, end)：单个最高需求的时段。

• compare_regions(start, end, regions=None)：跨区域的平均值和峰值。

• demand_vs_weather(region, start, end)：日需求数据与该区域温度数据的关联。

资源：

• schema://energy：数据库表的纯文本描述。

• docs://coverage：当前已加载的区域和日期范围。

提示词：

• analyze_demand(region)：一个引导用户通过工具分析某个区域的入门提示。

快速开始

你需要安装 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

要在一个界面中浏览这些工具，请使用MCP Inspector：

uv run mcp dev src/energy_mcp/server.py

连接到客户端

Claude Desktop

将此添加到 claude_desktop_config.json（在macOS上，路径为 ~/Library/Application Support/Claude/claude_desktop_config.json），然后重启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

然后使用自然语言提问，客户端会自动选择相应的工具：

• “2024年7月，美国哪个电网的平均需求最高？”

• “2024年ERCOT的峰值出现在什么时候？当天休斯顿有多热？”

• “比较CISO和PJM在1月第一周的需求。”

示例输出

客户端调用工具时，从捆绑数据中返回的真实结果：

> 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 是一个有趣的工具。ERCOT的需求随着夏季休斯顿温度的升高而上升（空调用电负荷），该工具会同时返回这两个序列，以便模型能够指出它们之间的关联。

数据

所有数据均为真实数据，并已截取至2024日历年，以确保文件大小保持在约5 MB。

SQLite文件已包含在仓库中，因此运行时无需获取任何数据。若要重新构建它或扩大日期范围（需要免费的EIA API密钥）：

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

设置 ENERGY_MCP_DB 环境变量，以使服务器指向不同的SQLite文件。

安全性

• 只读。数据库以SQLite的 mode=ro 模式打开，因此没有工具能够写入。

• 参数化SQL。参数作为绑定变量传递，而非直接格式化到查询字符串中，因此无法注入SQL。

• 输入验证。区域和日期参数在到达数据库之前会进行校验，错误的输入会返回清晰的错误信息，供模型处理。

• 无需密钥即可运行。数据包含在仓库中；EIA密钥仅用于重新构建数据。

开发

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

项目结构：

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

该项目使用MCP 1.x SDK（FastMCP API），这也是当前Claude Desktop文档和 mcp CLI所使用的版本。2.x SDK是一个较新的重新设计版本。

相关项目

energy-text2sql 是一个基于相同EIA和NOAA数据的文本转SQL智能体。相同的数据，不同的接口：前者通过编写SQL来回答问题，而本项目则将数据作为MCP工具提供。

许可证

MIT