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 클라이언트가 앱별로 사용자 정의 통합을 하는 대신 외부 도구를 호출하고 외부 데이터를 읽는 하나의 표준 방식을 제공합니다. 서버는 제공하는 기능을 공지하고, 클라이언트는 연결하여 사용합니다. 서버는 세 가지를 제공할 수 있습니다:

• 도구(Tools): 모델이 호출할 수 있는 함수.

• 리소스(Resources): 클라이언트가 컨텍스트로 로드하는 읽기 전용 콘텐츠.

• 프롬프트(Prompts): 사용자가 선택할 수 있는 재사용 가능한 템플릿.

이 서버는 세 가지를 모두 제공합니다.

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

UI에서 도구를 둘러보려면 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월에 평균 수요가 가장 높은 미국 전력망은?"

• "ERCOT의 2024년 최고 수요는 언제였고, 그날 휴스턴은 얼마나 더웠나?"

• "1월 첫째 주 동안 CISO와 PJM의 수요를 비교해줘."

예제 출력

클라이언트가 도구를 호출할 때 번들 데이터의 실제 결과:

> 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 수요는 여름철 휴스턴 기온과 함께 상승하며(에어컨 부하), 도구는 두 시리즈를 반환하므로 모델이 그 연관성을 지적할 수 있습니다.

데이터

모든 데이터는 실제 데이터이며, 파일 크기를 약 5MB로 유지하기 위해 2024년으로 제한되었습니다.

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에서 사용하는 SDK입니다. 2.x SDK는 새로운 재설계입니다.

관련 자료

energy-text2sql은 동일한 EIA 및 NOAA 데이터를 사용하는 텍스트-투-SQL 에이전트입니다. 동일한 데이터, 다른 인터페이스: 하나는 SQL을 작성하여 질문에 답하고, 이 서버는 데이터를 MCP 도구로 제공합니다.

라이선스

MIT