ESP RainMaker MCP Server Wrapper

Overview

ESP RainMaker MCP Server Wrapper exposes your ESP RainMaker devices to MCP-compatible clients (LLMs and apps) by wrapping the official esp-rainmaker-cli Python library in a local Model Context Protocol (MCP) server. Running locally, the wrapper translates MCP requests from clients (for example, Claude Desktop, Cursor, Windsurf, Gemini CLI) into calls to the esp-rainmaker-cli, which in turn uses the RainMaker cloud APIs with credentials stored on your machine.

This setup makes it easy to control and query ESP RainMaker devices using natural language or programmatic MCP calls while keeping authentication tokens local. The server is useful when you want to integrate voice assistants, code assistants, or LLMs with your ESP devices without building a custom backend.

GitHub: https://github.com/espressif/esp-rainmaker-mcp

Features

• Exposes esp-rainmaker-cli functionality over MCP so clients can:
  • Discover nodes and devices
  • Read device state and telemetry
  • Execute device actions (toggle, set values)
  • Manage basic device attributes
• Runs locally; uses existing esp-rainmaker-cli credentials (no re-auth through the server)
• Simple MCP server configuration compatible with major MCP clients
• Lightweight Python-based server—install and run inside a uv-managed environment

Prerequisites

Important: You must log in once with the standard esp-rainmaker-cli login flow (uv run esp-rainmaker-cli login) before starting the MCP server so saved credentials are available.

Installation / Configuration

1. Clone the repository and change into it:

git clone https://github.com/espressif/esp-rainmaker-mcp.git
cd esp-rainmaker-mcp

2. Install dependencies into a uv-managed environment:

uv sync

3. Log in to ESP RainMaker (one-time step):

uv run esp-rainmaker-cli login

4. Start the MCP server (example using uv run):

uv run --with esp-rainmaker-cli --with mcp[cli] mcp run /absolute/path/to/esp-rainmaker-mcp/server.py

Replace /absolute/path/to/esp-rainmaker-mcp/server.py with the absolute path on your system.

MCP client configuration (JSON)

Use the following JSON snippet when adding the server to MCP-capable clients. Replace the path to server.py:

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

Notes:

• The --with arguments ensure uv includes esp-rainmaker-cli and mcp when launching the server.
• Many clients (Cursor, Claude Desktop, Windsurf, Gemini CLI) accept an identical configuration block; add it to their config file or UI per client instructions.

Available Resources

The MCP server exposes a set of tools that mirror common esp-rainmaker-cli operations. Typical high-level resources and commands you can expect:

• list_nodes — list RainMaker nodes in your account
• get_node — fetch node details and devices
• list_devices — enumerate devices on a node
• get_device_state — read current device parameters and telemetry
• set_device_param — change a device parameter (on/off, brightness, setpoint)
• call_device_action — invoke an action or custom command
• get_logs/errors — return operation results or error messages

Clients will present these as MCP “tools” or actions; semantics and names may vary by client implementation.

How it Works (brief)

• The local MCP server listens for MCP tool invocations.
• When a request arrives, it invokes corresponding functions from esp-rainmaker-cli.
• esp-rainmaker-cli reads locally stored authentication tokens and forwards API calls to the RainMaker cloud.
• The server returns results (or structured errors) to the MCP client.

Security note: Credentials remain on your device. The server does not implement a login UI and does not attempt to capture user passwords; it relies on the standard CLI login flow.

Use Cases

• Natural language control: Ask an LLM in an MCP-enabled client to “Turn off the living room light” and have it call set_device_param on the correct device.
• Remote state inspection: Query device telemetry with prompts like “What’s the temperature reported by thermostat-1?”
• Batch operations: Use MCP to script actions across multiple devices, e.g., “Set all bedroom lights to 20%”.
• Troubleshooting: Request device status and last errors to assist debugging firmware or connectivity issues.
• Integration with desktop assistants: Add RainMaker device control to developer tools or chat-based automation workflows without building a custom backend.

Troubleshooting & Tips

• If tools return authentication errors, re-run: uv run esp-rainmaker-cli login
• Ensure the server.py path in your client config is absolute.
• Use uv sync whenever you change pyproject dependencies.
• Check server logs (stdout from uv run) for stack traces and API response details.

For source, issues, and contributions: https://github.com/espressif/esp-rainmaker-mcp