ESP RainMaker MCP Server

1# ESP RainMaker MCP Server
2 
3This project provides a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server wrapper around the [`esp-rainmaker-cli`](https://github.com/espressif/esp-rainmaker-cli) Python library.
4It allows MCP-compatible clients (like LLMs or applications such as Cursor, Claude Desktop, and Windsurf) to interact with your [ESP RainMaker](https://rainmaker.espressif.com/) devices using the official CLI.
5 
6## Introduction to Model Context Protocol (MCP)
7 
8The **Model Context Protocol (MCP)** is a standardized framework that enables AI systems to interact with external tools, data sources, and services in a unified manner. Introduced by Anthropic and adopted by major AI organizations, MCP acts as a universal interface, much like USB-C for hardware, allowing seamless integration across different platforms.
9 
10### Key Benefits of MCP in ESP RainMaker
11 
12- **Unified Interaction**: MCP allows AI models to access and control IoT devices using natural language prompts, making interactions more intuitive and accessible.
13- **Real-time Control**: With MCP, users can execute actions such as turning devices on/off, adjusting settings, and managing schedules directly through AI interfaces.
14- **Local Server, Cloud-Backed Control**: The ESP RainMaker MCP server runs locally and stores credentials on your machine. However, device management actions are performed via the official ESP RainMaker cloud APIs through the esp-rainmaker-cli.
15 
16By integrating MCP, the ESP RainMaker platform enhances its capabilities, allowing tools like Claude, Cursor, Windsurf, and Gemini CLI to manage IoT devices efficiently and securely.
17 
18## Prerequisites
19 
20*   **Python:** Version 3.10 or higher
21*   **uv:** The `uv` Python package manager. Install from [Astral's uv documentation](https://docs.astral.sh/uv/getting-started/installation/).
22*   **ESP RainMaker CLI Login:** You *must* have successfully logged into ESP RainMaker using the standard `esp-rainmaker-cli login` command in your terminal at least once. This server relies on the credentials saved by that process.
23*   **RainMaker Nodes** added into your account since onboarding isn't supported by the MCP server.
24 
25## Installation & Setup
26 
271.  **Clone the Repository:**
28    ```bash
29    git clone https://github.com/espressif/esp-rainmaker-mcp.git
30    cd esp-rainmaker-mcp
31    ```
32 
332.  **Install Dependencies using uv:**
34    This command installs `esp-rainmaker-cli`, `mcp[cli]`, and any other dependencies listed in `pyproject.toml` into a virtual environment managed by `uv`.
35 
36    ```bash
37    uv sync
38    ```
39    *(This assumes `uv` is installed)*
40 
413. **Login to ESP Rainmaker using `esp-rainmaker-cli`**
42    ```bash
43    uv run esp-rainmaker-cli login
44    ```
45 
46> [!NOTE]
47> Direct login via username/password within MCP is not supported for security reasons. Please use the standard CLI login flow first.
48 
49 
50## Client Configuration
51 
52To add this project as an MCP server in supported MCP clients (Cursor, Claude Desktop, Windsurf, and Gemini CLI), you'll need to add the same JSON configuration to each client's config file. The configuration is identical across all clients:
53 
54### MCP Server Configuration (All Clients)
55 
56Use the following JSON configuration for all MCP clients:
57 
58```json
59{
60   "mcpServers": {
61      "ESP-RainMaker-MCP": {
62         "command": "uv",
63         "args": [
64            "run",
65            "--with",
66            "esp-rainmaker-cli",
67            "--with",
68            "mcp[cli]",
69            "mcp",
70            "run",
71            "<absolute_path_to_repo>/server.py"
72         ]
73      }
74   }
75}
76```
77 
78> [!IMPORTANT]
79> Replace `<absolute_path_to_repo>/server.py` with the actual **absolute path** to the `server.py` file within the cloned `esp-rainmaker-mcp` directory on your system.
80 
81### Cursor MCP Server Setup
82 
831. Open Cursor and click on the settings (gear icon) at the top right.
84 
852. Navigate to "Tools & Integrations" from the settings menu.
86 
873. Click on "MCP Tools" in the integrations section.
88 
894. Click on "New MCP Server" to add a new server.
90 
915. This will open the mcp.json file. Add the JSON configuration shown above.
92 
93### Claude Desktop MCP Server Setup
94 
951. Open Claude Desktop and go to Settings -> Developer -> Edit Config.
96 
972. This will open the configuration file (claude_desktop_config.json). Add the JSON configuration shown above.
98 
993. Save the changes and restart Claude Desktop to apply the new settings.
100 
101### Windsurf MCP Server Setup
102 
1031. Open Windsurf and look for the hammer-type icon under the chat text input area.
104 
1052. Click on the hammer icon and select "Configure" from the options. This will open the plugins window.
106 
1073. Click on "View raw config" which will show you the `~/.codium/windsurf/mcp_config.json` file.
108 
1094. Add the JSON configuration shown above to the file.
110 
1115. Save the changes and click on "Refresh" under the chat text window to load the ESP RainMaker MCP tools.
112 
113### Gemini CLI MCP Server Setup
114 
1151. Locate your Gemini CLI settings file. On macOS, this is typically at `~/.gemini/settings.json`.
1162. Open the `settings.json` file in your preferred text editor.
1173. Add the JSON configuration shown above to the `mcpServers` section of the file. If the section does not exist, create it as shown in the example.
1184. Save the file and restart Gemini CLI if it is running.
119 
120> [!NOTE]
121> The configuration for all four applications (Cursor, Claude Desktop, Windsurf, and Gemini CLI) is the same, so you can use the same JSON structure for all of them.
122 
123> [!NOTE]
124> The `--with` arguments ensure `uv` includes the necessary dependencies when running the `mcp run` command.
125 
126## How it Works
127 
128This server acts as a bridge. It uses the `mcp` library to handle the Model Context Protocol communication. When a tool is called:
129 
1301.  It uses functions from the installed `esp-rainmaker-cli` library.
1312.  The library functions read locally stored authentication tokens.
1323.  It makes the necessary API calls to the ESP RainMaker cloud.
1334.  It returns the results (or errors) back through the MCP protocol.
134 
135 
136## Available Tools
137 
138This MCP server exposes the following tools for interacting with ESP RainMaker:
139 
140### Authentication & Configuration
141 
142*   `login_instructions()`:
143    *   Provides instructions (formatted with Markdown) on how to log in using the standard `esp-rainmaker-cli login` command in your terminal.
144        This server relies on the external CLI's browser-based login flow to securely store credentials.
145        Rendering as Markdown depends on the MCP client's capabilities.
146*   `check_login_status()`:
147    *   Checks if a valid login session exists based on credentials stored locally by `esp-rainmaker-cli`.
148        Confirms if the server can communicate with the ESP RainMaker backend.
149 
150### Node Management
151 
152*   `get_nodes()`:
153    *   Lists all node IDs associated with the logged-in user.
154*   `get_node_details(node_id: str = None, fields: str = None, name: str = None, type_: str = None)`:
155    *   Get detailed information for nodes including config, status, and params.
156    *   Supports filtering and field selection:
157        - `fields`: comma-separated list of fields to include (e.g. "node_id,name,type,config,params,status.connectivity,fw_version,mapping_timestamp")
158        - `name`: substring match (user-visible name from params)
159        - `type_`: substring match (device type)
160        - `node_id`: single node ID (for one node) or None (for all)
161    *   Returns a dict (single node) or list of dicts (all nodes).
162    *   Example:
163        ```python
164        get_node_details(ctx, fields="node_id,name,type")
165        ```
166*   `get_node_status(node_id: str)`:
167    *   Get the online/offline connectivity status for a specific node ID.
168*   `get_params(node_id: str)`:
169    *   Get current parameter values for a device.
170*   `set_params(node_id: str, params_dict: dict)`:
171    *   Set parameters for one or more devices.
172    *   `node_id`: Single ID or comma-separated list (e.g., "light1,light2")
173    *   `params_dict`: Parameters to set, e.g., `{"Light": {"Power": true}}`
174 
175### Schedule Management
176 
177*   `get_schedules(node_id: str)`:
178    *   Get schedules for a device.
179*   `set_schedule(node_id: str, operation: str, ...)`:
180    *   Manage device schedules.
181    *   `operation`: "add", "edit", "remove", "enable", or "disable"
182    *   For add/edit: Provide `name`, `trigger`, and `action`
183    *   Common triggers:
184        *   Daily 8 AM: `{"m": 480, "d": 127}`
185        *   Weekdays 6:30 PM: `{"m": 1110, "d": 31}`
186    *   Example action: `{"Light": {"Power": true}}`
187 
188### Group Management (Home/Room Hierarchy)
189 
190*   `create_group(name: str, group_type: str = None, ...)`:
191    *   Create a home or room.
192    *   Required: `name`, `group_type` ("home" or "room")
193    *   For rooms: `parent_group_id` required
194    *   Example: `create_group("Living Room", "room", parent_group_id="home_id")`
195 
196*   `get_group_details(group_id: str = None, include_nodes: bool = False)`:
197    *   Get group information. For all groups, use `group_id=None`.
198    *   Set `include_nodes=True` to include device details.
199    *   Returns: Group hierarchy, members, and metadata.
200 
201*   `update_group(group_id: str, ...)`:
202    *   Update group properties or manage devices.
203    *   Optional: `name`, `description`, `add_nodes`, `remove_nodes`
204    *   Examples:
205        *   Rename: `update_group("group_id", name="New Name")`
206        *   Add devices: `update_group("group_id", add_nodes="light1,light2")`
207 
208*   `add_device_to_room(device_node_id: str, room_group_id: str)`:
209    *   Add device to room (handles parent group automatically).
210    *   Example: `add_device_to_room("light1", "kitchen_id")`
211 
212## License
213 
214This project is licensed under the terms specified in the [LICENSE](LICENSE) file.
215