home / mcp / rainmaker mcp server

RainMaker MCP Server

Provides MCP access to ESP RainMaker devices via the official CLI for unified control and data readout.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "espressif-esp-rainmaker-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "esp-rainmaker-cli",
        "--with",
        "mcp[cli]",
        "mcp",
        "run",
        "<absolute_path_to_repo>/server.py"
      ]
    }
  }
}

You can use this MCP server to control ESP RainMaker devices from any MCP-enabled client. It bridges your local credentials stored by the official ESP RainMaker CLI to provide MCP-compatible actions and data access, letting you manage nodes, parameters, schedules, and groups through natural-language prompts and automated tools.

How to use

You interact with the ESP RainMaker MCP server through supported MCP clients. After configuring the server in your client, you can ask it to list devices, read or set device parameters, manage schedules, and organize devices into homes or rooms. The server performs actions via the ESP RainMaker cloud using the credentials stored by the standard CLI login flow.

How to install

Prerequisites you need before starting:

Python 3.10 or higher
uv Python package manager
ESP RainMaker CLI login completed at least once using esp-rainmaker-cli login
RainMaker Nodes added to your account after onboarding

Step-by-step setup commands you should run in your terminal:

# 1. Clone the MCP server repository
git clone https://github.com/espressif/esp-rainmaker-mcp.git
cd esp-rainmaker-mcp

# 2. Ensure uv is installed and install dependencies in a virtual environment
uv sync

# 3. Login to ESP RainMaker using the standard CLI flow
uv run esp-rainmaker-cli login

Additional notes

Security: Direct login via username/password within MCP is not supported. Use the standard cli login flow to securely store credentials.

Configuration for MCP clients

Use this MCP server configuration in each supported client to connect to the local MCP server. The configuration is identical across clients.

{
  "mcpServers": {
    "ESP-RainMaker-MCP": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "esp-rainmaker-cli",
        "--with",
        "mcp[cli]",
        "mcp",
        "run",
        "<absolute_path_to_repo>/server.py"
      ]
    }
  }
}

Available tools

login_instructions

Provides Markdown-formatted steps to log in using the standard esp-rainmaker-cli login flow. Uses the browser-based login flow to securely store credentials.

check_login_status

Verifies that a valid login session exists by checking locally stored credentials and confirms the MCP server can reach the ESP RainMaker backend.

get_nodes

Lists all node IDs associated with the logged-in user.

get_node_details

Fetches detailed information for one or more nodes, with optional field filtering and name/type-based subqueries.

get_node_status

Returns the online/offline connectivity status for a given node.

get_params

Retrieves current parameter values for a device.

set_params

Sets one or more device parameters. Supports single or multiple node IDs.

get_schedules

Fetches schedules configured for a device.

set_schedule

Manages device schedules by adding, editing, removing, enabling, or disabling.

create_group

Creates a home or room in the group hierarchy with required name and type.

get_group_details

Retrieves information about groups, with an option to include connected devices.

update_group

Updates group properties or manages the devices contained within a group.

add_device_to_room

Adds a device to a specific room, automatically handling parent group association.