md24de-mcp
This MCP server provides access to heating and hot-water consumption data from the German utility portal messdienst24.de.
Tools:
get_last_available_month— Retrieve the year and month of the most recently published consumption report.get_consumption_report— Obtain the full structured consumption report, including your kWh usage vs. average comparable households, comparisons to previous month and previous year, historical monthly readings, and property/object information.save_pdf— Download the official monthly UVI (unterjährige Verbrauchsinformation) PDF and save it to a local directory (default:~/Downloads), returning the file path, filename, reporting period, and file size.
Resources:
md24de://latest-report/pdf— Access the latest monthly UVI PDF directly in-memory (asapplication/pdf) without saving to disk.
Additional notes:
Results are cached in memory (default 30 minutes) to minimize portal requests; the PDF cache is shared between
save_pdfand the resource.Credentials are never logged; all communication is over HTTPS.
Supports natural-language queries like "How much heating energy did I use last month?" or "Compare my usage to last year."
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., "@md24de-mcp Show me my latest heating and hot water consumption."
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.
md24de-mcp
Unofficial Model Context Protocol (MCP) server for the messdienst24.de utility-consumption portal.
Wraps python-md24de to expose heating and hot-water consumption data as MCP tools that any MCP-compatible AI client can invoke.
Disclaimer — This project is not affiliated with, endorsed by, or in any way officially connected with messdienst24.de or its operators. Use at your own risk.
Resources
Resource URI | Description |
| The monthly UVI PDF document (application/pdf) |
Related MCP server: mastr-mcp-server
Tools
Tool | Description |
| Returns the year/month for which the portal currently provides data |
| Returns the full heating and hot-water consumption report |
| Saves the monthly consumption PDF to a local directory on disk |
get_last_available_month
Returns { "year": int, "month": int }.
get_consumption_report
Returns structured consumption data with the following shape:
{
"year": 2025,
"month": 4,
"object_info": { "object_number": "…", "address": "…" },
"heating": {
"your_kwh": 111.1,
"average_kwh": 222.2,
"vs_average": "less",
"vs_previous_month": "more",
"vs_previous_year": null,
"history": [
{ "year": 2025, "month": 4, "your_kwh": 111.1, "average_kwh": 222.2 },
{ "year": 2025, "month": 3, "your_kwh": 333.3, "average_kwh": 444.4 }
]
},
"hot_water": { "…": "…" }
}Comparison values are "less", "more", "equal", or null when unavailable.
save_pdf
Renders the PDF locally and saves it to a local directory on disk, returning:
{
"saved_to": "/Users/you/Downloads/verbrauch-2025-04.pdf",
"filename": "verbrauch-2025-04.pdf",
"year": 2025,
"month": 4,
"size_bytes": 123456
}The optional directory parameter controls where the file is saved (default: ~/Downloads).
To read the PDF content directly without saving to disk, use the resource
md24de://latest-report/pdf instead.
Note: The messdienst24.de portal no longer offers a downloadable PDF, so both the
save_pdftool and themd24de://latest-report/pdfresource render the UVI document locally via python-md24de (reportlab/Pillow, pulled in through its[pdf]extra — already a required dependency of this server, no extra setup needed).
Example prompts
Once connected to Claude Desktop, you can ask:
"How much heating energy did I use last month?"
"Am I using more or less heating than comparable households?"
"Show me my hot-water consumption trend over the past months."
"Compare my heating usage to last year's same month."
"Give me a summary of my energy consumption."
"Save my monthly consumption PDF to my Downloads folder."
"Save my monthly consumption PDF to my Desktop."
"Read my monthly UVI PDF document."
"Which month's data is currently available on messdienst24.de?"
Client lifecycle and caching
Each tool creates a fresh Md24deClient, performs the minimum required requests, then
closes the connection. This avoids server-side session timeouts for long-running processes.
Results are cached in memory for a configurable TTL (default 30 minutes):
Tool / Resource | Caches |
| available month |
| available month + consumption report |
| available month + PDF bytes |
| available month (if not already warm) + PDF bytes |
The save_pdf tool and the md24de://latest-report/pdf resource share the same PDF cache.
Reading one and then calling the other makes only one portal request.
Configuration
All configuration is provided via environment variables.
Variable | Required | Default | Description |
| ✓ | — | Short portal ID (the |
| ✓ | — | Portal login username |
| ✓ | — | Portal login password |
|
| HTTP request timeout in seconds | |
|
| Cache time-to-live in seconds | |
|
| Python logging level ( |
Installation
This package is not published on PyPI. The recommended way to install it for use with
Claude Desktop or other MCP clients is pipx, which installs
the md24de-mcp command globally while keeping its dependencies isolated:
pipx install "git+https://github.com/volsch/md24de-mcp.git@vX.Y.Z"Or with uv:
uv tool install "git+https://github.com/volsch/md24de-mcp.git@vX.Y.Z"Both put md24de-mcp on your PATH so MCP clients can launch it by name.
To upgrade to a newer version, replace vX.Y.Z and run pipx upgrade md24de-mcp or
uv tool upgrade md24de-mcp.
Running
export MD24DE_TENANT=xy
export MD24DE_USERNAME=your_user
export MD24DE_PASSWORD=your_pass
md24de-mcpMCP client configuration
Claude Desktop
1. Install the server (see Installation above, e.g. with pipx):
pipx install "git+https://github.com/volsch/md24de-mcp.git@vX.Y.Z"2. Add it to the Claude Desktop config.
Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"md24de": {
"command": "md24de-mcp",
"env": {
"MD24DE_TENANT": "xy",
"MD24DE_USERNAME": "your_user",
"MD24DE_PASSWORD": "your_pass"
}
}
}
}Replace xy, your_user, and your_pass with your actual messdienst24.de credentials.
The tenant ID is the md= value from your portal login URL (e.g. https://messdienst24.de/?md=xy).
3. Restart Claude Desktop.
4. Verify the connection.
A 🔧 icon in the chat input bar confirms the server is connected.
Click it to see the list of available tools (get_last_available_month, get_consumption_report, save_pdf) and the resource (md24de://latest-report/pdf).
5. Try an example prompt (see Example prompts above), e.g.:
"How much heating energy did I use last month?"
Logging
The server uses Python's standard logging module under the md24de_mcp logger hierarchy
and registers a NullHandler so no output appears unless the calling process configures
logging explicitly.
Set the LOG_LEVEL environment variable to control verbosity:
{
"mcpServers": {
"md24de": {
"command": "md24de-mcp",
"env": {
"MD24DE_TENANT": "xy",
"MD24DE_USERNAME": "your_user",
"MD24DE_PASSWORD": "your_pass",
"LOG_LEVEL": "DEBUG"
}
}
}
}Debug messages include cache hits/misses, available month/year values, and byte counts.
The underlying md24de library also emits debug messages (HTTP status codes, parsed dates).
Credentials (username, password) are never written to any log message.
Development
git clone https://github.com/volsch/md24de-mcp.git
cd md24de-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"Run the test suite:
pytestType-check:
pyright src/Lint and format:
ruff check src/ tests/
ruff format src/ tests/Legal
Legal context for the data
The monthly consumption report accessed through this server is the unterjährige Verbrauchsinformation (UVI) — a legally mandated document under §6a of the German Heating Cost Ordinance (Heizkostenverordnung, HeizkostenV). Under §6b HeizkostenV, consumption data may only be collected and used for billing purposes and to fulfil the legal information obligations. This server retrieves your own data from the portal provided for exactly that purpose.
Unofficial project
This server is not an official product of messdienst24.de. It was built by observing the portal's web interface for personal and educational use. It does not circumvent any technical protection measures and only uses credentials that the account holder provides themselves.
Credentials and privacy
Your username and password are passed directly to the messdienst24.de servers over HTTPS via the underlying python-md24de library. This server does not store or log credentials. However, any direct or indirect dependency — such as HTTP client internals, logging back-ends, or network proxies configured in your environment — is outside this server's control and may handle the data differently.
Consumption data fetched from the portal is held in memory only for the duration of the cache TTL and is never written to disk by this server.
No warranty
The portal's HTML structure can change at any time without notice, which may break the underlying library. The software is provided "as is" — see the LICENSE for full terms.
Terms of service
Before using this server, ensure your use complies with the messdienst24.de terms of service. Automated access may be restricted by those terms.
License
MIT © 2026 Volker Schmidt
Available Tools
3 toolsget_consumption_reportA
Return the heating and hot-water consumption report from messdienst24.de.
messdienst24.de is a German utility-consumption portal. This tool retrieves the full structured consumption data for your residential property. The report covers the most recently published month (returned as year/month at the top level) and also includes a history of several previous months so that trends can be analysed.
The response includes: year, month: The current reporting period (e.g. year=2025, month=4 for April 2025). object_info: Property address and object number assigned by the service provider. heating: Heating consumption data (see below). hot_water: Hot-water consumption data (same structure as heating).
Each meter section (heating / hot_water) contains: your_kwh: Your consumption for the current reporting month in kWh equivalent. average_kwh: Average consumption of comparable households in kWh equivalent. vs_average: How your usage compares to similar households this month. "less" = you used less, "more" = you used more, "equal" = same. null if the comparison is unavailable. vs_previous_month: How your usage compares to the previous month (same values). null if unavailable. vs_previous_year: How your usage compares to the same month last year (same values). null if unavailable. history: List of monthly readings for several past months, newest first. Each entry has year, month, your_kwh, average_kwh. history[0] always corresponds to the current reporting month.
Inputs: no named parameters. Returns: object
get_last_available_monthA
Return the month and year of the most recently published consumption report.
messdienst24.de is a German utility-consumption portal that provides the legally mandated monthly heating and hot-water consumption report (Verbrauchsinformation) for residential properties. The portal publishes one report per calendar month (always a previous month, never the current one). This tool returns which month that currently published report covers.
Call this tool when you only need to know the current reporting month without fetching the full report. The full report (get_consumption_report), the PDF resource (md24de://latest-report/pdf), and the save_pdf tool all include this information as well.
Returns: year: Four-digit year of the current reporting month (e.g. 2025). month: Month number 1–12 of the current reporting month (e.g. 4 for April).
Inputs: no named parameters. Returns: object
save_pdfA
Download the monthly consumption PDF and save it to disk.
This is the legally mandated unterjährige Verbrauchsinformation (UVI) document — a German statutory heating-cost information notice that property owners are required to provide to tenants under §6a HeizkostenV. The document is generated by the messdienst24.de portal and covers the same month returned by get_last_available_month.
Use this tool when the user explicitly wants the PDF saved to a local directory on disk. To read or forward the PDF content directly, use the resource md24de://latest-report/pdf instead.
Args: directory: Directory where the PDF will be saved. Defaults to ~/Downloads. The filename is set automatically to e.g. "verbrauch-2025-04.pdf".
Returns: saved_to: Full path of the saved file. filename: The filename used, e.g. "verbrauch-2025-04.pdf". year, month: The period the document covers. size_bytes: Size of the saved PDF in bytes.
Inputs: directory. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a clearly distinct purpose: get_consumption_report returns full structured data, get_last_available_month returns only the month metadata, and save_pdf downloads the PDF. No overlap in functionality.
All tool names follow a verb_noun pattern using snake_case (get_consumption_report, get_last_available_month, save_pdf). Naming is predictable and clear.
With 3 tools, the server covers the essential operations for accessing consumption report data: fetching structured data, checking the latest month, and saving the PDF. The count is appropriate for the narrow domain.
The tool set covers all necessary operations for the server's purpose: retrieving consumption data (full report), obtaining metadata (latest month), and persisting the PDF. No obvious gaps given the domain scope.
Maintenance
Related MCP Connectors
MCP server for Withings health data — sleep, activity, heart, and body metrics.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
MCP server for MOCO business software: time tracking, projects, budgets, and invoicing via API
MCP server providing attendance data queries via the CloudTime API.
Related MCP Servers
- AlicenseBqualityBmaintenanceMCP server for managing Yazio user & nutrition data (unofficial)473,097 npm72MIT
- AlicenseAqualityDmaintenanceMCP server for the German energy market master data register (MaStR), enabling querying of energy units, actors, grid connections, and more via 21 SOAP and public tools.724 PyPI6MIT
- AlicenseNot gradedqualityCmaintenanceRead-only MCP server for Tanita Health Planet measurements, providing tools for profile, health reporting, and measurement reads.MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for the air-Q Cloud API, enabling remote retrieval of air quality sensor data and historical analysis through read-only tools like listing devices, fetching readings, and exporting charts or data.50 PyPIApache 2.0