de en es ja ko ru zh

sens-mcp

Name: sens-mcp
Author: SofiaFlux

by SofiaFlux

Overview Schema Source Related Servers Discussions Admin

Python

Remote

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

환경 변수

변수	필수	기본값	설명
`SENS_API_KEY`	예	—	SENS API 키입니다. `X-API-KEY` 헤더로 전송됩니다.
`SENS_BASE_URL`	아니요	`https://api.getsens.energy`	스테이징/셀프호스팅 환경에서의 기본 URL을 재정의합니다.

Related MCP server: tibber-mcp-server

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 참고) — 위와 같은 형식입니다.

제공되는 도구

도구	목적
`resolve_operator(query, region=None)`	도시 또는 회사 이름(오타 허용)을 퍼지 매칭하여, API가 기대하는 정확한 `osd`/`sprzedawca` 문자열로 변환합니다.
`search_tariffs(customer_type, zone_preference=None, operator=None)`	고객 프로필(가정/소상놀인/산업)에 해당하는 유효한 요금 코드를 찾아냅니다.
`get_prices(osd, taryfa, ...)`	복합 전기 가격 및 요율 내역을 가져옵니다. 정확한 사용량 가중 총합을 원하면 `annual_kwh`를 전달하세요.
`get_tariff_components(tariff_id)`	요금제의 URE 승인 고정/변동 요율 구성 요소를 조사합니다.

리소스: 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

Available Tools

4 tools

get_pricesA

Fetch composite electricity prices and rate breakdown for a given OSD + tariff, optionally scoped to a retailer, date, market, region, and annual consumption. When annual_kwh is provided, the backend computes exact annual capacity fees and volume-weighted totals — never re-derive these client-side.

detail_level="summary" (default) strips verbose audit fields for token economy; use detail_level="detailed" for the full raw payload.

Name	Required	Default
`osd`	Yes
`date`	No
`page`	No
`size`	No
`since`	No
`market`	No
`region`	No
`taryfa`	Yes
`annual_kwh`	No
`sprzedawca`	No
`detail_level`	No	summary

Output Schema

Name	Required	Description
No output parameters

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the behavioral disclosure burden. It explains that annual_kwh triggers backend-side computation and explicitly warns against client-side re-derivation, and it clarifies the difference between summary and detailed outputs. It does not discuss pagination behavior or authentication, but the 'Fetch' verb implies a read operation and core behavior is disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and well-structured: the main purpose is front-loaded, and the second paragraph adds only high-value operational details. Every sentence earns its place, including the warning not to re-derive fees client-side.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter tool with no annotations and zero schema descriptions, the description covers the central workflow but omits pagination semantics, the role of 'since', and how this tool relates to its siblings. The presence of an output schema and clear core behavior makes it usable, but the definition is not fully complete for a complex tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It adds real meaning for annual_kwh and detail_level, and lightly maps sprzedawca to 'retailer' while mentioning date, market, region, and annual consumption as scoping options. However, it does not explain page, size, since, or the exact meaning of osd and taryfa beyond the phrase 'OSD + tariff', leaving several parameters only inferable from names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb ('Fetch') and a precise resource ('composite electricity prices and rate breakdown'), scoped to OSD and tariff. It naturally differentiates this tool from siblings like search_tariffs and get_tariff_components by focusing on composite price retrieval rather than tariff lookup or component extraction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly establishes the main use case: fetch prices for a given OSD and tariff, with optional filters. It gives practical guidance for annual_kwh and detail_level, but does not explicitly mention when not to use this tool or when a sibling would be preferable. Context is clear, but exclusions are absent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_tariff_componentsC

Inspect the detailed fixed/variable rate components of a tariff, as approved by URE (the Polish energy regulator).

Name	Required	Description	Default
`since`	No
`tariff_id`	Yes

Output Schema

Name	Required	Description
No output parameters

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'inspect' which weakly implies a read-only operation, but it does not mention whether the tool returns historical/current data, how 'since' affects behavior, what happens for invalid tariff IDs, or any authorization requirements. The 'as approved by URE' detail adds domain context but no behavioral transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, focused sentence with no fluff. It front-loads the core purpose and includes a relevant regulatory qualifier. Nothing extraneous is present, and it is appropriately brief for a straightforward lookup tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having an output schema (which covers return values), the description omits key operational context: the optional 'since' parameter is absent, no usage example or prerequisite is given, and the relationship between this tool and get_prices is unclear. For a tool with two params and zero schema descriptions, this is insufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not mention either parameter. The 'since' parameter is completely unexplained, and even 'tariff_id' gets no elaboration beyond its name. The description provides zero added meaning beyond the input schema's property titles.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Inspect') and resource ('detailed fixed/variable rate components of a tariff'), instantly distinguishing it from siblings like search_tariffs or get_prices. The clarification about URE approval adds regulatory context. This is unambiguous and free of tautology.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is for inspecting tariff components, but it gives no explicit guidance on when to choose it over get_prices, resolve_operator, or search_tariffs. There are no stated conditions, exclusions, or alternative pointers. The context is limited to a generic 'this is what it does'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

resolve_operatorA

Resolve a natural-language city or company name to the exact OSD (distribution operator) and default retailer strings the SENS API expects.

Example: query="Kraków" or query="enea". Handles typos via fuzzy matching.

Name	Required	Description	Default
`query`	Yes
`region`	No

Output Schema

Name	Required	Description
No output parameters

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It explicitly discloses the fuzzy-matching typo behavior and the exact-string output expectation. It does not cover edge cases like no-match behavior, but the key behavioral traits are present.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences plus an example line. Every sentence earns its place: purpose, example inputs, and fuzzy behavior are all stated without filler. The most important information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple resolver with an output schema, the description covers purpose, fuzzy behavior, and expected output. The missing region semantics is a real gap, but the overall definition is largely complete and actionable for the common query-only case.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It explains the query parameter through examples and semantics, but the region parameter is never mentioned at all, leaving one of the two parameters completely undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb 'Resolve' and names both the input (natural-language city/company name) and the output (exact OSD/default retailer strings for the SENS API). This clearly differentiates it from the sibling search/get tariff tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly indicates when to use this tool: when you have a fuzzy or natural-language operator name and need the canonical API strings. It gives concrete examples. It does not explicitly list exclusions or alternative tools, but the intended scenario is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_tariffsA

Discover valid tariff codes tailored to a customer profile (household, small business, or industry), optionally narrowed by zone preference and operator.

Name	Required	Description	Default
`operator`	No
`customer_type`	Yes
`zone_preference`	No

Output Schema

Name	Required	Description
No output parameters

TDQS

A3.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the behavioral burden. 'Discover' implies a read-only search and 'optionally narrowed' describes filtering behavior, but it does not disclose prerequisites such as whether the operator should be resolved first, what happens when no results match, or whether the output is limited to codes rather than prices.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single front-loaded sentence with no filler. It states the core action first and then the optional modifiers, with every phrase contributing to the agent's understanding of what to pass and why.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a low-complexity search tool with an output schema, the description covers the main operation and filter semantics. But there are no annotations, no guidance on sibling-tool workflows, and no statement about whether customer_type is required or what the default behavior is when optional filters are omitted.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It maps customer_type to a 'customer profile' and clarifies that zone_preference and operator are optional narrowing filters. However, it does not explain what 'operator' means or the semantics behind the zone enum values, so the compensation is only partial.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Discover') and a specific resource ('valid tariff codes'), and clearly scopes the results to a customer profile with optional zone/operator filters. This semantically distinguishes it from sibling tools like get_prices and get_tariff_components, which target different outputs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool: when tariff codes are needed for a customer type, optionally narrowed by zone or operator. However, it provides no explicit when-not-to-use guidance, no mention of alternatives, and does not explain how this tool relates to resolve_operator or get_prices.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

4 tool updatesv0.1.0Aug 26, 2026
- First observedget_prices
- First observedget_tariff_components
- First observedresolve_operator
- First observedsearch_tariffs

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored 2026-08-26 01:10 across 4 tools

Disambiguation5/5

Each tool targets a distinct stage in the workflow: resolution of operator names, tariff discovery, tariff component inspection, and price fetching. No overlapping responsibilities or ambiguous boundaries.

Naming Consistency5/5

All four tools follow a consistent verb_noun pattern with snake_case (resolve_operator, search_tariffs, get_tariff_components, get_prices). The verbs (resolve, search, get) are clear and uniform.

Tool Count5/5

Four tools is well-scoped for a focused API covering Polish energy tariffs and prices. Each tool serves a distinct, necessary function without redundancy or bloat.

Completeness5/5

The tool set provides a complete workflow: resolve an operator, search for tariffs, inspect tariff components, and fetch prices with breakdowns. No obvious gaps or dead ends exist for the stated purpose of retrieving energy pricing information.

Maintenance

ActivityActive

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

Elecz Electricity Price Signal APIA
io.github.zemloai-ctrl
Real-time electricity prices for AI agents. 40+ countries, 100+ zones. No auth required.
Energy Home Automation & IoT Research & Data
325
https://elecz.com/mcp
Elecz Electricity Price SignalA
com.elecz
Real-time electricity price signals for AI agents. Spot prices, cheapest hours, and contract recommendations. 31 countries across Europe and Oceania. No authentication required.
Energy Finance Home Automation & IoT
32
https://elecz.com/mcp
DryosA
ai.dryos
Live US power market prices, load, generation, weather and permits for AI agents.
Energy Weather Services Open Data
51
https://api.dryos.ai/mcp
AhelA
ai.ahel
Data and tools for your AI agent: company, people, SEO, social and EU register data. Pay per call.
Research & Data Social Media Government Data
111
https://mcp.ahel.ai

Related MCP Servers

Datadis MCP Server
Energy Research & Data
Jaimegruiz
A
license
Not graded
quality
D
maintenance
Enables AI agents to access and analyze Spanish electricity consumption data via the Datadis API, providing tools for supply management, consumption analysis, anomaly detection, and executive reporting.
Updated 4 months ago (2026-07-04 07:48 UTC)
MIT
tibber-mcp-server
Energy Home Automation & IoT
Schimmilab
A
license
A
quality
A
maintenance
Enables querying Tibber electricity prices, forecasts, consumption data, cheapest hours, and live Pulse measurements through natural language.
Updated a day ago (2026-11-05 10:57 UTC)
7
MIT
Elecz MCP Server
Energy Open Data
zemloai-ctrl
F
license
Not graded
quality
C
maintenance
Provides real-time electricity prices, cheapest hours, and contract comparison for 40+ countries, enabling AI agents to make energy-aware decisions.
Updated 4 months ago (2026-07-07 16:39 UTC)
5
-
mcp-octopus-energy
Energy Open Data
pipeworx-io
A
license
Not graded
quality
B
maintenance
Enables AI agents to query UK energy tariffs and products via the Octopus Energy public API.
Updated 3 days ago (2026-11-03 21:09 UTC)
619 npm
MIT

sens-mcp

빠른 시작

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

pup으로 설치하기(대안)

환경 변수

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

Claude Desktop

Cursor

제공되는 도구

개발자 예시(MCP 불필요)

API 레퍼런스 (주요)

개발

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

라이선스

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

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