Esp Rainmaker MCP

What espressif/esp-rainmaker-mcp MCP server does

The espressif/esp-rainmaker-mcp MCP server exposes ESP RainMaker device management through the Model Context Protocol. It is intended for MCP clients that need to inspect and control devices associated with a logged-in ESP RainMaker account.

Available operations include listing node IDs, retrieving node details, filtering nodes by ID, name, or device type, and selecting specific response fields. Agents can check whether a node is online, read current parameter values, and set parameters on one or more nodes. For example, a parameter payload can change a light's power state.

The server also provides schedule operations. Clients can retrieve schedules and add, edit, remove, enable, or disable them. Schedule inputs support triggers such as daily or weekday times and actions such as changing a device parameter. Group operations cover creating homes or rooms and retrieving group details, optionally including associated nodes.

How it works

The espressif/esp-rainmaker-mcp MCP server uses the MCP library for client communication and delegates ESP RainMaker operations to the esp-rainmaker-cli Python library. The CLI reads authentication data stored locally on the machine. Requests made through MCP are then sent to the official ESP RainMaker cloud APIs, with results or errors returned to the connected client.

This architecture separates local MCP execution from cloud-backed device control. The server itself does not provide a separate login flow; it depends on a successful CLI login and the credentials saved by that process.

Setup and configuration

Python 3.10 or newer and the uv package manager are required. After cloning the repository, install its dependencies with uv sync. The setup includes the ESP RainMaker CLI, the MCP CLI components, and dependencies declared by the project.

Before starting the MCP server, run uv run esp-rainmaker-cli login and complete the standard CLI login flow. Direct username and password login through MCP is not supported. The repository also states that RainMaker nodes must already be present in the account because onboarding is outside the server's scope.

Client configuration uses a local uv command that runs mcp run against the repository's server.py file. The file path must be replaced with the absolute path on the host. The same configuration structure is documented for Claude Desktop, Cursor, Windsurf, and Gemini CLI.

Tools and capabilities

The espressif/esp-rainmaker-mcp MCP server exposes tools for:

• Providing CLI login instructions and checking stored login status.
• Listing nodes and retrieving filtered or field-selected node details.
• Reading node connectivity and current parameter values.
• Setting parameters for one node or a comma-separated list of nodes.
• Reading and modifying device schedules.
• Creating home or room groups and retrieving group information.

Node detail filters include a single node ID, a substring of the user-visible name, and a substring of the device type. Field selection can limit returned data to values such as node ID, name, type, configuration, parameters, connectivity, firmware version, or mapping timestamp.

Limitations and notes

A valid ESP RainMaker CLI login is required before device tools can work. Credentials are stored locally by the CLI, while device actions use the ESP RainMaker cloud APIs. The server does not support entering RainMaker credentials directly through MCP.

The documented client setup requires a local checkout and an absolute path to server.py; a hosted endpoint is not described. Node onboarding is not included, so devices need to have been added to the RainMaker account separately. The available examples and parameters also depend on the device model and its RainMaker configuration.