The ESP RainMaker MCP server provides Model Context Protocol (MCP)-based interaction capabilities for ESP RainMaker devices. MCP is a standardized framework proposed by Anthropic that enables AI systems to interact with external tools, data sources, and services in a unified way. The ESP RainMaker MCP server is a wrapper that encapsulates the esp-rainmaker-cli Python library, allowing MCP-compatible clients (such as LLMs or applications like Cursor, Claude Desktop, Windsurf, and Gemini CLI) to control devices through the official CLI.
Main capabilities include:
- Authentication and configuration: provides login instructions (login_instructions) and checks login status (check_login_status).
- Node management: lists all node IDs (get_nodes), gets node details (get_node_details), supports filtering by field, name, and type; gets node online/offline status (get_node_status); gets current parameter values (get_params); sets parameters for one or more devices (set_params).
- Schedule management: gets device schedules (get_schedules); sets schedules (set_schedule), supports add, edit, delete, enable, and disable operations, and can specify names, trigger conditions, and actions.
- Group management (home/room hierarchy): creates a home or room (create_group); gets group details (get_group_details); updates group attributes or manages devices (update_group); adds a device to a room (add_device_to_room).
Usage:
- Environment requirements: Python 3.10 or higher; the uv package manager; must have successfully logged in at least once in the terminal via the esp-rainmaker-cli login command.
- Installation steps: clone the repository (git clone https://github.com/espressif/esp-rainmaker-mcp.git），进入目录（cd esp-rainmaker-mcp), use uv sync to install dependencies (including esp-rainmaker-cli, mcp[cli], etc.), then run uv run esp-rainmaker-cli login to log in.
- Client configuration: add the same JSON configuration in supported MCP clients (Cursor, Claude Desktop, Windsurf, Gemini CLI), replacing <absolute_path_to_repo>/server.py with the actual absolute path. Configuration locations for each client: Cursor opens mcp.json via Settings > Tools & Integrations > MCP Tools > New MCP Server; Claude Desktop edits claude_desktop_config.json via Settings > Developer > Edit Config; Windsurf edits ~/.codium/windsurf/mcp_config.json by clicking the hammer icon > Configure > View raw config; Gemini CLI edits the mcpServers section in ~/.gemini/settings.json.
Applicable scenarios: Suitable for users who want to manage ESP RainMaker IoT devices through natural language or AI clients, enabling device switching, parameter adjustment, schedule setting, and group management without manually operating the CLI.
Limitations:
- Requires Python 3.10+ and the uv package manager.
- Must log in in advance through esp-rainmaker-cli; direct login with username/password in MCP is not supported.
- The server runs locally, and credentials are stored locally, but device management operations are performed through cloud APIs, so a network connection is required.
- The MCP server does not support RainMaker nodes added to an already logged-in account.
- The project adopts the license terms specified in the LICENSE file.
