sens-mcp
This MCP server lets AI agents query SENS Polish electricity market data through four tools.
Resolve city/company names to exact OSD and retailer strings with fuzzy matching.
Search valid tariff codes for household, small business, or industry profiles, optionally by zone and operator.
Fetch composite electricity prices and rate breakdowns for an OSD/tariff, with optional date, market, region, retailer, annual consumption, pagination, and summary/detailed output.
Inspect URE-approved fixed and variable rate components for a tariff ID.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@sens-mcp Show me current electricity prices for the G11 tariff in Warsaw"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
sens-mcp
An MCP (Model Context Protocol) server and developer starter kit for the SENS Energy Data API — the Polish electricity market data API (distribution operators, tariffs, and composite price calculations).
It solves the "cold start" problem for LLMs and AI agents (Claude Desktop,
Cursor, LangChain, n8n, ...) talking to the API: the Polish energy market has
its own vocabulary (OSD vs. sprzedawca, tariff groups G11/G12/G12w/...)
that models don't know out of the box, and raw REST responses are too large
and too easy to miscalculate against by hand.
sens-mcp provides:
Zero-shot discoverability — an MCP resource (
sens://market/cheat-sheet) and discovery tools (resolve_operator,search_tariffs) that teach the model the market vocabulary in under ~400 tokens.Actionable self-correction — tool errors return structured JSON with suggestions (
did you mean G12w?) instead of raw HTTP failures, so an agent in a ReAct loop can repair its own next call.Single source of truth calculations — all price/volume math happens on the SENS backend; the toolkit never re-derives totals client-side.
Non-blocking startup — the server boots instantly with an embedded fallback market schema; live tariff metadata refreshes in the background.
Quickstart
Run via uvx (recommended, no install step)
export SENS_API_KEY=sens_live_your_key_here
uvx sens-mcpOr install with pip
pip install sens-mcp
export SENS_API_KEY=sens_live_your_key_here
python -m sens_mcpEnvironment variables
Variable | Required | Default | Description |
| Yes | — | Your SENS API key. Sent as the |
| No |
| Override for staging/self-hosted deployments. |
Related MCP server: tibber-mcp-server
Using it with an AI agent
Claude Desktop
Add to claude_desktop_config.json (see configs/claude_desktop_config.json):
{
"mcpServers": {
"sens-energy": {
"command": "uvx",
"args": ["sens-mcp"],
"env": {
"SENS_API_KEY": "sens_live_your_key_here"
}
}
}
}Cursor
Add to .cursor/mcp.json (see configs/cursor_mcp.json) — same shape as above.
Tools exposed
Tool | Purpose |
| Fuzzy-resolve a city or company name (typo-tolerant) to the exact |
| Discover valid tariff codes for a customer profile (home / small business / industry). |
| Fetch composite electricity prices and rate breakdown; pass |
| Inspect a tariff's URE-approved fixed/variable rate components. |
| Nationwide regulated fees: capacity fee (household bands, per-kWh business rate + charging window), OZE, cogeneration. |
| URE indicators: average market/quarterly/household prices, combined averages per tariff group, risk-free rate, CO2 forward price. |
Resource: sens://market/cheat-sheet — a Markdown cheat sheet of Polish
electricity market vocabulary (OSDs, tariff groups, price component
structure).
Developer examples (no MCP required)
Standalone snippets that hit the SENS REST API directly:
examples/python/async_stream.py— delta sync viasince
API reference (essentials)
Base URL:
https://api.getsens.energyAuth:
X-API-KEY: <your key>header (not Bearer, not a query param).GET /api/v1/prices—osd,sprzedawca,taryfa,market,date,annual_kwh,region,since,page,size(max 1000).GET /api/v1/tariffs—since/If-Modified-Sincefor delta queries,page,size.GET /api/v1/tariffs/components?tariff_id=...— component breakdown for a single tariff, also supportssince.
Full Swagger/OpenAPI docs: https://api.getsens.energy/api/docs.
Full developer documentation (quickstart, MCP integration guide, market
vocabulary): docs.getsens.energy.
Development
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytestTests mock all HTTP calls with respx —
nothing in the default test suite hits the live API.
Live integration suite (opt-in)
tests/test_live_integration.py runs the real server as a subprocess over
the real MCP stdio protocol against the real production SENS API, and checks
byte-for-byte parity between MCP tool responses and raw httpx calls to the
same endpoints. Excluded by default; run explicitly with a real key:
SENS_API_KEY=<a real key> pytest -m live tests/test_live_integration.py -vLicense
MIT
Available Tools
4 toolsget_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.
Inputs: osd (required), taryfa (required), date, page, +7 more. Returns: object
get_tariff_componentsC
Inspect the detailed fixed/variable rate components of a tariff, as approved by URE (the Polish energy regulator).
Inputs: tariff_id (required), since. Returns: object
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.
Inputs: query (required), region. Returns: object
search_tariffsA
Discover valid tariff codes tailored to a customer profile (household, small business, or industry), optionally narrowed by zone preference and operator.
Inputs: customer_type (required), operator, zone_preference. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
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.
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.
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.
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
Related MCP Connectors
Real-time electricity prices for AI agents. 40+ countries, 100+ zones. No auth required.
Real-time electricity price signals for AI agents. Spot prices, cheapest hours, and contract recommendations. 31 countries across Europe and Oceania. No authentication required.
Live US power market prices, load, generation, weather and permits for AI agents.
Data and tools for your AI agent: company, people, SEO, social and EU register data. Pay per call.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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.MIT
- AlicenseAqualityBmaintenanceEnables querying Tibber electricity prices, forecasts, consumption data, cheapest hours, and live Pulse measurements through natural language.7MIT
- FlicenseNot gradedqualityDmaintenanceProvides real-time electricity prices, cheapest hours, and contract comparison for 40+ countries, enabling AI agents to make energy-aware decisions.5-
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to query UK energy tariffs and products via the Octopus Energy public API.89 npmMIT