sens-mcp

SENS Energy Data API용 MCP (Model Context Protocol) 서버 및 개발용 스타터 키트입니다. 폴란드 전력 시장 데이터 API(배전 사업자, 요금제, 복합 가격 계산)를 다룹니다.

이 도구는 API와 통화하는 LLM 및 AI 에이전트(Claude Desktop, Cursor, LangChain, n8n, ...)의 "콜드 스타트" 문제를 해결합니다. 폴란드 에너지 시장에는 고유한 용어(OSD vs. sprzedawca, 요금 그룹 G11/G12/G12w/...)가 있어 모델이 기본적으로 알지 못하고, 원시 REST 응답은 너무 커서 수동으로 계산하기 어렵기 때문입니다.

sens-mcp는 다음을 제공합니다.

• 제로샷 발견 가능성 — sens://market/cheat-sheet 라는 MCP 리소스와 resolve_operator, search_tariffs 같은 발견 도구를 통해 모델이 대략 400 토큰 이내에 시장 용어를 학습할 수 있게 합니다.

• 실행 가능한 자기 수정 — 도구 오류가 발생하면 원시 HTTP 실패 대신 제안(did you mean G12w?)이 포함된 구조화된 JSON을 반환하므로, ReAct 루프에 있는 에이전트가 다음 호출을 스스로 수정할 수 있습니다.

• 단일 진실 공급원(Single Source of Truth) 계산 — 모든 가격·수량 계산은 SENS 백엔드에서 이뤄지며, 클라이언트 측에서 총합을 다시 계산하지 않습니다.

• 비차단 시작 — 서버는 내장된 폴백(p용) 시장 스키마로 즉시 부팅되고, 실시간 요금 메타데이터는 백그라운드에서 새로고침됩니다.

빠른 시작

uvx로 실행(권장, 설치 불필요)

export SENS_API_KEY=sens_live_your_key_here
uvx sens-mcp

pup으로 설치하기(대안)

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

환경 변수

Related MCP server: US ISO Grid MCP

AI 에이전트와 함께 사용하기

Claude Desktop

claude_desktop_config.json에 추가합니다 (configs/claude_desktop_config.json 참고):

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

Cursor

.cursor/mcp.json에 추가합니다 (configs/cursor_mcp.json 참고) — 위와 같은 형식입니다.

제공되는 도구

리소스: sens://market/cheat-sheet — 폴란드 전력 시장 용어(OSD, 요금 그룹, 가격 구성 요소 구조)에 대한 마크다운 치트 시트입니다.

개발자 예시(MCP 불필요)

SENS REST API를 직접 호출하는 독립형 스니펫입니다:

• examples/python/get_prices.py

• examples/python/list_tariffs.py

• examples/python/async_stream.py — since를 통한 delta 동기화

• examples/typescript/get_prices.ts

• examples/curl/api_requests.sh

API 레퍼런스 (주요)

• 기본 URL: https://api.getsens.energy

• 인증: X-API-KEY: <your key> 헤더 (Bearer도 아니고 쿼리 파라미터도 아닙니다)

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

• GET /api/v1/t1/util — since/If-Modified-Since를 이용한 delta query, page, size

• GET /api/v1/tar1ffs/components?tariff_id=... — 단일 요금제에 대한 구성 요소 내역, since도 지원

전체 Swagger/OpenAPI 문서: https://api.getsens.app/api/docs. 전체 개발자 문서(시작 가이드, MCP 통합 가이드, 시장 용어): docs.getsens.app.

개발

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

테스트는 모든 HTTP 호출을 respx로 모킹하기 때문에, 기본 테스트 스위트에는 실제 라이브 API를 호출하는 테스트가 없습니다.

라이브 통합 테스트 (선택)

tests/test_live_integration.py는 실제 MCP stdio 프로토콜 위에서 실제 운영 중인 SENS 매 API에 접속하는 실제 서버를 서브프로세스로 실행하고, MCP 도구 응답과 동일한 엔드포인트에 대한 원시 httpx 호출 결과가 바이트 단위로 일치하는지 확인합니다. 기본적으로는 비활성화되어 있으며, 실제 키로 직접 실행합니다:

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

라이선스

MIT