emsesp-mcp-server

<div align="center"> <img src="images/logo.png" alt="Logo" width="100" height="100"> <h2>MCP Server for Bosch/Buderus heat pumps</h2> <p>LLM-powered chat for your heat pump</p>

</div>

---

<div align="center"> <img src="https://i.ibb.co/G4qzST84/claude-desktop-dhw-cop.gif" width="672" alt="Get dhw temperature and COP of preparation" /> <p>Get hot water temperature and COP of preparation</p> </div>

---

<div align="center"> <img src="https://i.ibb.co/NdYDgCPy/Claude-show-heat-curve-small.gif" alt="Get graph of configured heat curve" /> <p>Get graph of configured heat curve</p> </div>

📔 Table of Contents

• About
• Integration in LLM Application
• Configuration
• Available Tools
• Outlook

🚀 About

With this Model Context Protocol (MCP) server, you can integrate your Bosch CS5800/6800i or Buderus WLW176/186i heat pump via ems-esp into a Large Language Model (LLM) Application such as Claude Desktop.

Then shoot your prompts like so:

• Is hot water preparation running right now?
• What's the current outdoor temperature?
• How warm is the domestic hot water at the moment?
• How much electricity is my heat pump currently using?
• What's the COP (Coefficient of Performance) for hot water preparation?

The LLM will select the necessary Tools provided by the MCP server to answer the question.

Or you can simply use the built-in Prompts provided by the MCP server:

• /show-dhw-settings to get all settings for domestic hot water preparation in table format
• /show-heat-curve to show the configured heat curve as a graph
• ... more to come soon - stay tuned! 👀

✍️ Integration in LLM Application

This MCP server works with any LLM application which supports Tools. I've verified it end-to-end on the Claude Desktop App which supports easy one-click installation.

Install in Claude Desktop App with DXT file

1. Download latest emsesp-mcp-server.dxt file
2. Open Settings in Claude Desktop
3. Go to Extensions and drag the DXT file into the window
4. Press Install
5. Change the URL of your EMS-ESP gateway if necessary
6. Close the window and start chatting with your heat pump 💬

Manual installation

Go to the settings file of your LLM application, for instance .vscode/mcp.json for Github Copilot, and add the following configuration:

"emsesp": {
  "type": "stdio",
  "command": "npx",
  "args": [
    "-y",
    "github:bosch-buderus-wp/emsesp-mcp-server"
  ],
  "env": {
    "EMS_ESP_URL": "http://ems-esp"
  }
}

⚙️ Configuration

• LOG_LEVEL (info): The log level of the logs which get written to ~/.emsesp-mcp/server-%DATE%.log
• EMS_ESP_URL (http://ems-esp): Base URL of the EMS-ESP gateway
• ENTITIES_CONFIG_PATH (./entities.json): Path to the entity configuration file
• TAGS_AS_TOOLS (statistics,temperatures,states,settings,pumps,eheater): comma-separated list of tags. Each tag gets exposed as a separate tool. Each tool provides all entities which are tagged with the respective tag in the config file stored at ENTITIES_CONFIG_PATH.

🛠️ Available Tools

The MCP server in the current initial version provides read-only Tools which can be chosen by the LLM according to its needs. To reduce token size in the response and reduce irrelevant noise in the response, the huge list of entities provided by EMS-ESP has been reduced to a meaningful minimum and structured into groups with entities for similar categories like statistics or temperatures. To support the LLM in selecting the right tool and interpreting the response correctly - hopefully with as little hallucinations as possible, tools and the returned entities are well described.

Each entity of EMS-ESP has a list of tags in entity.json:

"dhw.nrg": {
      "title": "Total heat energy generated for hot water",
      "tags": ["statistics", "energy", "dhw", "prod-nrg"]
    },

All entities associated to a tag are exposed with the respective MCP tool.

If you want to add more entities, copy entity.json and add your additional entities. Then you can use the modified file in the MCP server via the environment variable ENTITIES_CONFIG_PATH=<path-to-modified-file>.

👓 Outlook

• More entities and prompts
• Tools to set room temperature, start desinfection, enable PV surplus, adapt dhw settings, ...
• Resources providing more context on the topic

📄 License

MIT