Skip to main content
Glama

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

list_sections(lang)

Table of contents (section ids like 6.1, 16.8, 21.5)

get_section(section_id, lang)

Full Markdown of a section (6 includes 6.1, 6.2, …)

search_kb(query, lang, max_results)

Accent-insensitive keyword search over paragraphs and table rows

lookup_terminal(terminal, lang)

Everything about one terminal: 211, 303, 1L1, PE5, 357, …

lookup_register(register, lang)

Everything about one EXT-bus register: r32, 0x33, 19 (hex)

list_images() / get_image(name)

Pre-rendered schematic pages (name or unique fragment, e.g. ELEC_p040)

list_source_documents()

The original PDFs with their citation tags

get_source_page(source, page, dpi)

Render any page of an original PDF, e.g. source="ELEC", page=40

get_source_page_text(source, page)

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-mcp

Claude Code

claude mcp add thermia-kb -- uvx --from git+https://github.com/vazluis83/thermia-kb-mcp thermia-kb-mcp

Claude 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/mcp

The 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

INST_Duo-installation_9680-54961001.pdf

Thermia Duo – Installation instructions, v4

ELEC

ELEC_Duo-electrical-installation_9680-55353001.pdf

Thermia Duo – Electrical installation (all Duo schematics), Rev 2

USER

USER_Duo-user-manual_9680-54962001.pdf

Thermia Duo – User's manual, Rev 2

EXP1

EXP1_Diplomat-expansion-card_9680-55173001.pdf

Thermia Diplomat expansion card, Rev 3

EXP2

EXP2_Expansion-card-install_086U6715.pdf

Expansion card installation 086U6715 (multilingual)

COOL

COOL_Cooling-module-install_086U7815.pdf

Cooling module passive / passive-active 086U7815 (multilingual)

FAN

FAN_Zantia-ventiloconvectores.pdf

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]"
pytest

Safety

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 tools
get_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

    A3.8/5.0

    Scored across 10 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      3
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides AI agents with manufacturer-sourced HVAC technical documentation, enabling error-code lookup, diagnostics, and guided troubleshooting with exact source citations.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      5
      MIT