emsesp

This MCP server exposes a set of read-only Tools that map EMS-ESP entities (Bosch/Buderus heat pump data) into a شكل that an LLM can query. It enables your LLM application to ask for hot water settings, temperatures, COP, power usage, and other monitored metrics, and then the MCP will return structured responses from the EMS-ESP gateway. You can use it with Claude Desktop or any MCP client that supports Tools. In typical usage, the LLM selects a Tool corresponding to a category (e.g., statistics, temperatures, settings) and the server returns the relevant EMS-ESP data. Prompts provided by the server include commands like /show-dhw-settings and /show-heat-curve to inspect current configurations. To integrate into an LLM workflow, configure your MCP client to point at the server (via npx deployment or a direct run) and ensure the EMS_ESP_URL points to your EMS-ESP gateway.

Prerequisites:

• Node.js and npm installed on your machine (npm install/node available) or a runtime environment that can run npx.
• Access to a networking endpoint where EMS-ESP is reachable (EMS_ESP_URL).

Installation steps:

1. Ensure you have Node.js installed (LTS version recommended).
2. Run the MCP server using npx, as shown in the example:

npx -y github:bosch-buderus-wp/emsesp-mcp-server

3. If you need to customize environment variables (EMS_ESP_URL, logging, or tool exposure), you can prefix the command with env variables, for example:

EMS_ESP_URL=http://ems-esp LOG_LEVEL=info ENTITIES_CONFIG_PATH=./entities.json TAGS_AS_TOOLS=statistics,temperatures,states,settings,pumps,eheater npx -y github:bosch-buderus-wp/emsesp-mcp-server

4. If you’re using Claude Desktop or a similar LLM client, you can import the provided MCP configuration (see manual example in the README) and point the client to the MCP server. You can also manually set up a config like the following in your MCP client:

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

5. Verify the server starts and the EMS-ESP gateway is reachable at the URL you provided.

Tips and common considerations:

• The server exposes entities grouped by tags (statistics, temperatures, states, settings, pumps, e heater). If you need more or different entities, you can modify ENTITIES_CONFIG_PATH to point to a custom entities.json that includes your desired tags.
• Adjust LOG_LEVEL to control the verbosity of logs written to the server log file (~/.emsesp-mcp/server-%DATE%.log).
• Ensure EMS_ESP_URL is reachable from the MCP server host; firewalls or network policies may require allowing access to the EMS-ESP gateway.
• If you encounter token length or response size issues, rely on the tool descriptions and entity groupings to keep responses concise for the LLM.
• This initial version focuses on read-only Tools; future updates may add write capabilities.