thermia-kb-mcp
This MCP server exposes a bilingual, source-cited Thermia Duo 12 heat-pump knowledge base plus its original manuals for AI-assisted lookup and verification.
Browse the table of contents and retrieve full sections in English or Portuguese.
Search paragraphs, list items, and table rows with accent-insensitive keyword search.
Look up control-unit terminals and EXT-bus registers with wiring, function, units, ranges, and source pages.
List and retrieve pre-rendered schematic/drawing images.
List the original PDF manuals, render any cited PDF page, or extract a page’s text to verify citations.
Read the complete knowledge base as the
kb://enorkb://ptresource.
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., "@thermia-kb-mcp Show me the EXT I2C register map for the Thermia Duo 12"
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.
thermia-kb-mcp
An MCP server that gives any AI assistant (Claude, ChatGPT, Cursor, local models, …) a verified technical knowledge base for the Thermia Duo 12, 400 V 3N ground-source heat pump, plus the original manuals it was built from.
It is meant for people building their own controller or monitor (ESP32 / ESPHome / Home Assistant) for this pump, and for anyone servicing or wiring one.
What is in it
Knowledge base in English and European Portuguese, ~1,000 lines each:
specifications
power and control wiring with wire numbers
every control-unit terminal (211–220, 301–334)
sensor resistance tables with Steinhart–Hart fits
start/stop logic, menus, all factory settings with limits, alarms
expansion card, cooling module, fan coils
ESP32 integration: the EXT I2C bus with the full register map, the room-sensor protocol on 303/304, and EVU on 307/308
Every fact carries its source and PDF page, e.g.
[ELEC p.40].Facts read from drawings or reverse-engineered by the community are marked as such.
45 pre-rendered schematic pages.
The 7 original PDFs (~29 MB). The server can render or extract text from any page, so a model can verify a citation itself.
Covers the standard Duo 12 (drawing 56960) and the Duo Optimum 12 (drawing 57156). Much of it also applies to the other Duo sizes and to Diplomat / Danfoss DHP pumps of the same generation, but check against your own unit.
Tools
Tool | What it does |
| Table of contents (section ids like |
| Full Markdown of a section ( |
| Accent-insensitive keyword search over paragraphs and table rows |
| Everything about one terminal: |
| Everything about one EXT-bus register: |
| Pre-rendered schematic pages (name or unique fragment, e.g. |
| The original PDFs with their citation tags |
| Render any page of an original PDF, e.g. |
| Text layer of one PDF page |
Resource: kb://en, kb://pt – the complete knowledge base. lang is en (default) or pt.
Related MCP server: pi-kb-mcp
Install and connect
Requires Python ≥ 3.10. The easiest way is uv, which runs it straight from GitHub:
uvx --from git+https://github.com/vazluis83/thermia-kb-mcp thermia-kb-mcpClaude Code
claude mcp add thermia-kb -- uvx --from git+https://github.com/vazluis83/thermia-kb-mcp thermia-kb-mcpClaude Desktop / other clients using a JSON config
{
"mcpServers": {
"thermia-kb": {
"command": "uvx",
"args": ["--from", "git+https://github.com/vazluis83/thermia-kb-mcp", "thermia-kb-mcp"]
}
}
}Without uv
pip install git+https://github.com/vazluis83/thermia-kb-mcp
thermia-kb-mcp # stdio
thermia-kb-mcp --http --host 0.0.0.0 --port 8000 # streamable HTTP at http://HOST:8000/mcpThe knowledge base itself is plain Markdown, so you can also read it directly or paste it into any model:
src/thermia_kb_mcp/data/thermia-duo12-knowledge-base-EN.md ·
…-PT.md.
Source documents
Tag | File | Document |
INST |
| Thermia Duo – Installation instructions, v4 |
ELEC |
| Thermia Duo – Electrical installation (all Duo schematics), Rev 2 |
USER |
| Thermia Duo – User's manual, Rev 2 |
EXP1 |
| Thermia Diplomat expansion card, Rev 3 |
EXP2 |
| Expansion card installation 086U6715 (multilingual) |
COOL |
| Cooling module passive / passive-active 086U7815 (multilingual) |
FAN |
| Zantia fan-coil catalogue (Portuguese) |
Page numbers in citations are PDF page numbers.
Contributing corrections
The knowledge base changes only through reviewed issues. Nothing is learned or committed automatically. If you verified on your own unit that something is wrong or missing, open an issue with the correction template, saying how you verified it: measurement, display reading, register dump, or document and page. Models using the server are told to point users here only for verified findings.
Development
pip install -e ".[test]"
pytestSafety
This is reference information, not instructions to work on live equipment. The pump runs on 400 V three-phase: mains work must be done by a qualified electrician. Never bypass the pump's safety devices (pressure switches B1/B2/B3, overload F11, heater guard T1). Writing to the pump over the EXT bus is unacknowledged and at your own risk.
Credits and licences
Server code and the knowledge-base text: MIT (see LICENSE).
EXT-bus protocol, register map and room-sensor protocol come from mdepa91/esphome-thermia, mdepa91/esphome-thermia-room (MIT) and ThermIQ/thermiq_mqtt-ha (MIT), building on reverse engineering by rainisto.
The PDF manuals and the images rendered from them are © their respective owners (Thermia Värme AB / Danfoss, Zantia). They are included unmodified for reference by owners of this equipment and are not covered by the MIT licence. Rights holders can ask for removal by opening an issue.
Not affiliated with Thermia, Danfoss or Zantia.
Available Tools
10 toolsget_imageA
Return one image (PNG/JPG; SVG is returned as an image with format svg+xml). Accepts the exact name or a unique fragment such as 'ELEC_p040' or 'sheet3_external'.
Inputs: name (required).
get_sectionA
Return the full Markdown of a section. A top-level id like '6' includes its subsections; '6.1' returns only that subsection. lang: 'en' or 'pt'.
Inputs: section_id (required), lang. Returns: result
get_source_pageA
Render one page of an original PDF so you can check a citation or read a schematic yourself. source: tag INST, ELEC, USER, EXP1, EXP2, COOL or FAN. page: PDF page number exactly as cited in the knowledge base (e.g. [ELEC p.40] -> source='ELEC', page=40). dpi 50–300; use ~200 for dense schematics.
Inputs: page (required), source (required), dpi.
get_source_page_textA
Extract the text layer of one page of an original PDF (same arguments as get_source_page). Schematic pages contain little text; render them with get_source_page instead.
Inputs: page (required), source (required). Returns: result
list_imagesB
Names of the rendered schematic / drawing images. Names encode source and PDF page, e.g. 'ELEC_p040_Duo12-400V_sheet2_control-unit-E1.png' = electrical installation manual, PDF page 40.
Inputs: no named parameters. Returns: result
list_sectionsB
List all numbered sections of the knowledge base (id, title, level). lang: 'en' or 'pt'.
Inputs: lang. Returns: result
list_source_documentsA
The original PDF manuals the knowledge base was built from: tag (as used in citations like [ELEC p.40]), file name, page count and title.
Inputs: no named parameters. Returns: result
lookup_registerA
Everything about one EXT-bus register (ThermIQ map, as used by esphome-thermia): accepts 'r32', '0x32' or '32' (hex). Returns the register-map rows with meaning, unit, range, matching pump menu parameter and whether it is confirmed on real hardware.
Inputs: register (required), lang. Returns: result
lookup_terminalB
Every table row / note mentioning a terminal of the heat pump, expansion card or cooling module, e.g. '211', '303', '1L1', 'PE5', '251', '357'. Gives function, wiring, wire number and source page.
Inputs: terminal (required), lang. Returns: result
search_kbA
Keyword search over paragraphs, list items and table rows (accent-insensitive). Returns the best matching blocks with their section id; read the section with get_section for context. lang: 'en' or 'pt'.
Inputs: query (required), lang, max_results. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool has a distinct role: section browsing (list_sections/get_section) vs. free-text search (search_kb), and two orthogonal technical lookups (lookup_terminal for wiring terminals, lookup_register for EXT-bus registers). The only mild overlap is get_image (pre-rendered schematics) vs. get_source_page (render any PDF page), but the descriptions make the boundary reasonably clear.
Consistent snake_case verb_noun pattern throughout (list_sections, get_section, search_kb, lookup_terminal, lookup_register, list_images, get_image, list_source_documents, get_source_page, get_source_page_text). Suffixed variants like get_source_page_text logically extend their base tool rather than breaking the convention.
10 tools is well within the ideal 3-15 range and each earns its place: browsing, search, two specialized lookups, image access, and raw PDF access. No redundant or filler tools.
Read-only KB coverage is strong: navigation, search, targeted technical lookups, images, and access to original PDFs (both render and text layer) cover the main workflows. Minor gap: lookup_terminal and lookup_register require a known key and offer no way to enumerate all terminals or registers, which could stall an exploratory query.
Maintenance
Related MCP Connectors
Search and query nTop's knowledge base and engineering guides from AI applications.
Bring your Knacco library into your AI tool: browse, search, read guides and download files.
Shared knowledge base for AI agents. Search and contribute solutions to technical problems.
Verified answers for AI agents: only from approved documents, with sources, or a refusal.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables AI assistants to read and write selected values from IDM heat pumps via Modbus TCP, providing controlled access to operational data and setpoints.3MIT
- AlicenseAqualityBmaintenanceEnables searching and reading AVEVA Customer Support Portal knowledge base articles, including tech notes, known issues, and error-message diagnostics, to ground AI answers in support content not found in public documentation.3MIT
- AlicenseNot gradedqualityCmaintenanceProvides AI agents with manufacturer-sourced HVAC technical documentation, enabling error-code lookup, diagnostics, and guided troubleshooting with exact source citations.MIT

MyLeadTech MCPofficial
AlicenseAqualityBmaintenanceEnables users to resolve HVAC model and nameplate references, search OEM documents for fault codes and specifications, and receive written answers with page-level citations for Carrier, Trane, and Lennox equipment.5MIT