ESP RainMaker MCP Server Gateway

This repository furnishes a Model Context Protocol (MCP) server wrapper, utilizing the underlying esp-rainmaker-cli Python utility. It grants MCP-compliant consumer applications (such as advanced LLMs like Claude, development assistants like Cursor, or specialized clients like Windsurf) the ability to interface with and govern your personal ESP RainMaker connected hardware using the authorized command-line toolset.

Understanding the Model Context Protocol (MCP)

The Model Context Protocol (MCP) establishes a standardized mechanism enabling sophisticated AI entities to communicate with external resources, data repositories, and operational services in a cohesive manner. Championed by Anthropic and adopted broadly across the AI sector, MCP functions as a universal adapter layer—analogous to USB-C in electronics—ensuring smooth interoperability across diverse software environments.

Advantages of MCP Integration for ESP RainMaker

• Standardized Access: MCP permits artificial intelligence engines to manipulate and query IoT apparatuses using natural language instructions, fostering greater ease of use.
• Immediate Operational Control: Via MCP, end-users can trigger immediate device modifications, including power state toggling, configuration adjustments, and temporal scheduling updates, directly through their AI interface.
• Hybrid Control Architecture: While this specialized MCP server executes locally, securing user authentication tokens on the host machine, all device control operations are relayed through the official ESP RainMaker cloud infrastructure via the esp-rainmaker-cli backend.

By implementing MCP, the ESP RainMaker ecosystem significantly boosts its utility, empowering tools such as Gemini CLI, Claude, Cursor, and Windsurf to manage smart devices efficiently and with robust security.

Necessary Preconditions

• Python Runtime: Version 3.10 or newer is mandatory.
• Package Manager: The uv Python package manager is required. Installation instructions are available on Astral's uv documentation.
• RainMaker CLI Authentication: You must complete the initial esp-rainmaker-cli login sequence in your system terminal at least once. This server depends entirely on the session credentials persisted by that preparatory step.
• Device Onboarding Note: The MCP server component does not support the initial onboarding or provisioning of new RainMaker nodes into your account.

Setup and Deployment Procedure

1. Obtain the Source Code: bash git clone https://github.com/espressif/esp-rainmaker-mcp.git cd esp-rainmaker-mcp

2. Dependency Installation via uv: This command leverages uv to build a dedicated virtual environment and install all required packages listed in pyproject.toml, including esp-rainmaker-cli and mcp[cli].

   bash uv sync

   (This step presumes uv is accessible in your PATH)

3. Establish ESP Rainmaker Credentials via CLI bash uv run esp-rainmaker-cli login

[!CAUTION] For security compliance, direct credential submission (username/password) through the MCP interface is intentionally disallowed. Initial authentication must occur using the standard CLI utility first.

Client Integration Configuration

To integrate this utility as an active MCP endpoint within supported LLM clients (e.g., Claude Desktop, Cursor, Windsurf, Gemini CLI), you must insert the following identical JSON structure into each client's respective configuration file:

Universal MCP Server Definition (For All Clients)

Employ this JSON block across all compatible MCP clients:

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

[!WARNING] Substitute <absolute_path_to_repo>/server.py with the fully qualified, absolute file system path to server.py located within your cloned esp-rainmaker-mcp directory.

Configuration Guides for Specific Clients

(The detailed steps for Cursor, Claude Desktop, Windsurf, and Gemini CLI setup are retained here for completeness, focusing on where to place the configuration block.)

[... Detailed Setup Steps for Cursor, Claude Desktop, Windsurf, and Gemini CLI ...]

[!TIP] The --with arguments provided to uv are crucial; they guarantee that the required esp-rainmaker-cli and mcp[cli] dependencies are loaded into the execution context before the mcp run command initiates the server.

Operational Flow Summary

This server functions strictly as a secure intermediary. It leverages the external mcp library to manage all Model Context Protocol communications. Upon invocation by a connected tool:

1. It calls the appropriate functions exposed by the installed esp-rainmaker-cli library.
2. The library accesses authentication tokens stored locally on your machine.
3. Secure API calls are routed to the ESP RainMaker cloud service.
4. The resulting data payload (or any encountered errors) is returned back to the calling client via the MCP framework.

Exposed Functional Interfaces

This server makes the following specialized tools available for controlling ESP RainMaker resources:

Authentication and Status Checking

• login_instructions():
  • Outputs Markdown-formatted guidance instructing the user to utilize the standard esp-rainmaker-cli login flow in their shell. Relies on the CLI's built-in secure browser authentication method.
• check_login_status():
  • Verifies the presence and validity of the locally stored credentials, confirming the server's ability to connect to the ESP RainMaker backend.

Device (Node) Orchestration

• get_nodes():
  • Retrieves a comprehensive manifest of all device identifiers linked to the authenticated user account.
• get_node_details(node_id: str = None, fields: str = None, name: str = None, type_: str = None):
  • Fetches comprehensive metadata for specified nodes, including configuration parameters, current operational status, and firmware information.
  • Filtering Capabilities:
    • fields: A comma-separated string specifying desired output attributes (e.g., "node_id,name,status.connectivity").
    • name: Filters results based on a partial match against the user-friendly device name.
    • type_: Filters based on a partial match against the device's hardware classification.
    • node_id: Targets a single, specific node, or retrieves all if set to None.
  • Return Type: A dictionary for a single node or a list of dictionaries for multiple nodes.
• get_node_status(node_id: str):
  • Returns the real-time connectivity state (online/offline) for a specified device identifier.
• get_params(node_id: str):
  • Retrieves the current settable values for a designated device.
• set_params(node_id: str, params_dict: dict):
  • Applies new parameter settings across one or more devices.
  • node_id: Can accept a single ID or a comma-separated string of IDs (e.g., "bulb_a,switch_b").
  • params_dict: A nested dictionary defining the required state change, e.g., {"Switch": {"Power": false}}.

Temporal Scheduling Control

• get_schedules(node_id: str):
  • Fetches all existing timed operations scheduled for a particular device.
• set_schedule(node_id: str, operation: str, ...):
  • Manages the lifecycle of device schedules.
  • operation: Must be one of: "add", "edit", "remove", "enable", or "disable".
  • For creation/modification ("add"/"edit"): Requires specification of a name, a temporal trigger, and an executable action.
  • Example Triggers:
    • Daily at 08:00 UTC: {"m": 480, "d": 127}
    • Weekdays at 18:30 UTC: {"m": 1110, "d": 31}
  • Example Action: {"Light": {"Brightness": 50}}

Hierarchical Group Management (Rooms/Homes)

• create_group(name: str, group_type: str = None, ...):

  • Provisions a new organizational container, designated as either a "home" or a "room".
  • Mandatory inputs: name and group_type ("home" or "room").
  • Rooms require the specification of a parent_group_id.
  • Example: create_group("Office Area", "room", parent_group_id="home_id_123")

• get_group_details(group_id: str = None, include_nodes: bool = False):

  • Retrieves structural data for groups. If group_id is omitted (None), it returns details for the entire hierarchy.
  • Setting include_nodes=True enriches the output with the full details of member devices.

• update_group(group_id: str, ...):

  • Modifies an existing group's properties or manages its device membership.
  • Optional update parameters: name, description, add_nodes (comma-separated list), remove_nodes.
  • Usage Examples:
    • Rename: update_group("g_xyz", name="New Name")
    • Add Devices: update_group("g_xyz", add_nodes="sensor4,actuator9")

• add_device_to_room(device_node_id: str, room_group_id: str):

  • A convenience function to map a specific device identifier into a designated room ID, automatically handling implicit parent group association.
  • Example: add_device_to_room("light_kitchen_1", "room_kitchen_id")

Licensing Information

This software is distributed under the terms detailed in the official LICENSE document.

WIKIPEDIA: Google Cloud Platform (GCP) encompasses a comprehensive suite of cloud computing services provided by Google, offering modular capabilities in computation, data persistence, advanced analytics, and machine learning, supplemented by robust management tooling. As documented by Verma et al., this platform operates on the identical foundational infrastructure utilized internally by Google for its consumer-facing products such as Gmail, Google Docs, and Google Search. Account creation mandates the provision of payment information, either a credit card or bank account details.

GCP delivers services spanning Infrastructure as a Service (IaaS), Platform as a Service (PaaS), and serverless computational environments.

Google's foray into cloud computing services began in April 2008 with the announcement of App Engine, a system designed for the development and hosting of web applications within Google's managed data centers. This service reached general availability in November 2011. Following App Engine's introduction, Google systematically augmented the platform with numerous additional cloud offerings.

Google Cloud Platform constitutes a major segment of the broader 'Google Cloud' entity, which incorporates the public cloud infrastructure of GCP, the enterprise software suite Google Workspace (formerly G Suite), business editions of Android and ChromeOS, and specialized Application Programming Interfaces (APIs) for machine intelligence and enterprise geospatial services. Since at least 2022, official Google communications frequently use "Google Cloud" as the definitive replacement for "Google Cloud Platform," a transition that can occasionally lead to nomenclature ambiguity.

== Key Service Offerings == Google catalog lists upwards of 100 distinct products under the Google Cloud branding. A selection of principal services follows.

=== Computation Services === App Engine – A Platform as a Service environment supporting application deployment written in languages including Java, PHP, Node.js, Python, C#, .Net, Ruby, and Go. Compute Engine – Infrastructure as a Service providing scalable execution environments for both Linux and Microsoft Windows virtual machines. Google Kubernetes Engine (GKE) or GKE on-prem (part of Anthos) – A Container as a Service solution built upon the Kubernetes orchestration standard. Cloud Functions – A Functions as a Service framework for running short-lived, event-driven code snippets in Node.js, Java, Python, or Go. Cloud Run – A flexible compute execution substrate based on Knative principles. Available in a fully managed configuration or as Cloud Run for Anthos, currently supporting management across GCP, AWS, and VMware environments.

=== Data Persistence and Databases === Cloud Storage – Unified object storage solution incorporating integrated edge caching for handling unstructured data. Cloud SQL – A managed Database as a Service supporting relational engines like MySQL, PostgreSQL, and Microsoft SQL Server. Cloud Bigtable – A managed, high-throughput NoSQL database service. Cloud Spanner – A globally distributed, strongly consistent, relational database engineered for horizontal scalability. Cloud Datastore – A NoSQL data store optimized for mobile and web applications. Persistent Disk – Block-level storage volumes provisioned for use with Compute Engine virtual machines. Cloud Memorystore – Managed in-memory caching services based on Redis and Memcached technologies. Local SSD: High-speed, ephemeral, locally attached block storage resources. Filestore: A high-performance, managed file storage service designed for Google Cloud users. AlloyDB: A fully managed, proprietary database service compatible with PostgreSQL.

=== Network Infrastructure ===

VPC – Virtual Private Cloud, providing isolated network segments within the Google infrastructure.