Skip to main content
Glama
README.md
# thermia-kb-mcp

An [MCP](https://modelcontextprotocol.io) 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`.

## Install and connect

Requires Python ≥ 3.10. The easiest way is [uv](https://docs.astral.sh/uv/), which runs it straight from GitHub:

```sh
uvx --from git+https://github.com/vazluis83/thermia-kb-mcp thermia-kb-mcp
```

**Claude Code**

```sh
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**

```json
{
  "mcpServers": {
    "thermia-kb": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/vazluis83/thermia-kb-mcp", "thermia-kb-mcp"]
    }
  }
}
```

**Without uv**

```sh
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`](src/thermia_kb_mcp/data/thermia-duo12-knowledge-base-EN.md) ·
[`…-PT.md`](src/thermia_kb_mcp/data/thermia-duo12-knowledge-base-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](https://github.com/vazluis83/thermia-kb-mcp/issues/new/choose), 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

```sh
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](LICENSE)).
- EXT-bus protocol, register map and room-sensor protocol come from
  [mdepa91/esphome-thermia](https://github.com/mdepa91/esphome-thermia),
  [mdepa91/esphome-thermia-room](https://github.com/mdepa91/esphome-thermia-room) (MIT) and
  [ThermIQ/thermiq_mqtt-ha](https://github.com/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.

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