ESP RainMaker MCP Server
OfficialAllows interaction with ESP RainMaker IoT devices, enabling management of nodes, parameters, schedules, and groups via the Espressif cloud platform.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ESP RainMaker MCP Serverlist all my RainMaker devices"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ESP RainMaker MCP Server
This project provides a Model Context Protocol (MCP) server wrapper around the esp-rainmaker-cli Python library.
It allows MCP-compatible clients (like LLMs or applications such as Cursor, Claude Desktop, and Windsurf) to interact with your ESP RainMaker devices using the official CLI.
Introduction to Model Context Protocol (MCP)
The 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.
Key Benefits of MCP in ESP RainMaker
Unified Interaction: MCP allows AI models to access and control IoT devices using natural language prompts, making interactions more intuitive and accessible.
Real-time Control: With MCP, users can execute actions such as turning devices on/off, adjusting settings, and managing schedules directly through AI interfaces.
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.
By 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.
Related MCP server: WiseVision/mcp_server_ros_2
Prerequisites
Python: Version 3.10 or higher
uv: The
uvPython package manager. Install from Astral's uv documentation.ESP RainMaker CLI Login: You must have successfully logged into ESP RainMaker using the standard
esp-rainmaker-cli logincommand in your terminal at least once. This server relies on the credentials saved by that process.RainMaker Nodes added into your account since onboarding isn't supported by the MCP server.
Installation & Setup
Clone the Repository:
git clone https://github.com/espressif/esp-rainmaker-mcp.git cd esp-rainmaker-mcpInstall Dependencies using uv: This command installs
esp-rainmaker-cli,mcp[cli], and any other dependencies listed inpyproject.tomlinto a virtual environment managed byuv.uv sync(This assumes
uvis installed)Login to ESP Rainmaker using
esp-rainmaker-cliuv run esp-rainmaker-cli login
Direct login via username/password within MCP is not supported for security reasons. Please use the standard CLI login flow first.
Client Configuration
To 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:
MCP Server Configuration (All Clients)
Use the following JSON configuration for all MCP clients:
{
"mcpServers": {
"ESP-RainMaker-MCP": {
"command": "uv",
"args": [
"run",
"--with",
"esp-rainmaker-cli",
"--with",
"mcp[cli]",
"mcp",
"run",
"<absolute_path_to_repo>/server.py"
]
}
}
}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.
Cursor MCP Server Setup
Open Cursor and click on the settings (gear icon) at the top right.
Navigate to "Tools & Integrations" from the settings menu.
Click on "MCP Tools" in the integrations section.
Click on "New MCP Server" to add a new server.
This will open the mcp.json file. Add the JSON configuration shown above.
Claude Desktop MCP Server Setup
Open Claude Desktop and go to Settings -> Developer -> Edit Config.
This will open the configuration file (claude_desktop_config.json). Add the JSON configuration shown above.
Save the changes and restart Claude Desktop to apply the new settings.
Windsurf MCP Server Setup
Open Windsurf and look for the hammer-type icon under the chat text input area.
Click on the hammer icon and select "Configure" from the options. This will open the plugins window.
Click on "View raw config" which will show you the
~/.codium/windsurf/mcp_config.jsonfile.Add the JSON configuration shown above to the file.
Save the changes and click on "Refresh" under the chat text window to load the ESP RainMaker MCP tools.
Gemini CLI MCP Server Setup
Locate your Gemini CLI settings file. On macOS, this is typically at
~/.gemini/settings.json.Open the
settings.jsonfile in your preferred text editor.Add the JSON configuration shown above to the
mcpServerssection of the file. If the section does not exist, create it as shown in the example.Save the file and restart Gemini CLI if it is running.
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.
The--with arguments ensure uv includes the necessary dependencies when running the mcp run command.
How it Works
This server acts as a bridge. It uses the mcp library to handle the Model Context Protocol communication. When a tool is called:
It uses functions from the installed
esp-rainmaker-clilibrary.The library functions read locally stored authentication tokens.
It makes the necessary API calls to the ESP RainMaker cloud.
It returns the results (or errors) back through the MCP protocol.
Available Tools
This MCP server exposes the following tools for interacting with ESP RainMaker:
Authentication & Configuration
login_instructions():Provides instructions (formatted with Markdown) on how to log in using the standard
esp-rainmaker-cli logincommand in your terminal. This server relies on the external CLI's browser-based login flow to securely store credentials. Rendering as Markdown depends on the MCP client's capabilities.
check_login_status():Checks if a valid login session exists based on credentials stored locally by
esp-rainmaker-cli. Confirms if the server can communicate with the ESP RainMaker backend.
Node Management
get_nodes():Lists all node IDs associated with the logged-in user.
get_node_details(node_id: str = None, fields: str = None, name: str = None, type_: str = None):Get detailed information for nodes including config, status, and params.
Supports filtering and field selection:
fields: comma-separated list of fields to include (e.g. "node_id,name,type,config,params,status.connectivity,fw_version,mapping_timestamp")name: substring match (user-visible name from params)type_: substring match (device type)node_id: single node ID (for one node) or None (for all)
Returns a dict (single node) or list of dicts (all nodes).
Example:
get_node_details(ctx, fields="node_id,name,type")
get_node_status(node_id: str):Get the online/offline connectivity status for a specific node ID.
get_params(node_id: str):Get current parameter values for a device.
set_params(node_id: str, params_dict: dict):Set parameters for one or more devices.
node_id: Single ID or comma-separated list (e.g., "light1,light2")params_dict: Parameters to set, e.g.,{"Light": {"Power": true}}
Schedule Management
get_schedules(node_id: str):Get schedules for a device.
set_schedule(node_id: str, operation: str, ...):Manage device schedules.
operation: "add", "edit", "remove", "enable", or "disable"For add/edit: Provide
name,trigger, andactionCommon triggers:
Daily 8 AM:
{"m": 480, "d": 127}Weekdays 6:30 PM:
{"m": 1110, "d": 31}
Example action:
{"Light": {"Power": true}}
Group Management (Home/Room Hierarchy)
create_group(name: str, group_type: str = None, ...):Create a home or room.
Required:
name,group_type("home" or "room")For rooms:
parent_group_idrequiredExample:
create_group("Living Room", "room", parent_group_id="home_id")
get_group_details(group_id: str = None, include_nodes: bool = False):Get group information. For all groups, use
group_id=None.Set
include_nodes=Trueto include device details.Returns: Group hierarchy, members, and metadata.
update_group(group_id: str, ...):Update group properties or manage devices.
Optional:
name,description,add_nodes,remove_nodesExamples:
Rename:
update_group("group_id", name="New Name")Add devices:
update_group("group_id", add_nodes="light1,light2")
add_device_to_room(device_node_id: str, room_group_id: str):Add device to room (handles parent group automatically).
Example:
add_device_to_room("light1", "kitchen_id")
License
This project is licensed under the terms specified in the LICENSE file.
Available Tools
13 toolsadd_device_to_roomA
Add a device to a room with automatic parent group handling.
This function automatically handles the ESP RainMaker hierarchy requirement:
First adds the device to the parent group (e.g., "My Home")
Then adds the device to the target room group (e.g., "Kitchen")
Parameters:
device_node_id: The node ID of the device to add
room_group_id: The group ID of the room to add the device to
This is a convenience function that makes the hierarchical behavior explicit.
| Name | Required | Description | Default |
|---|---|---|---|
| device_node_id | Yes | ||
| room_group_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses the two-step process (adding to parent group then room) and mentions the underlying hierarchy requirement. It does not cover error conditions or side effects, but for a simple tool this is reasonable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-line summary, a multi-step explanation, and parameter definitions. Every sentence adds value; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 2 simple string parameters and an existing output schema, the description covers purpose, steps, and parameters adequately. It could mention error cases (e.g., missing group), but overall it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage. The description adds basic meaning: device_node_id is the node ID, room_group_id is the group ID. It does not provide examples, format, or additional constraints, but it compensates for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool adds a device to a room with automatic parent group handling, distinguishing it from siblings like create_group or get_node_details. The verb 'add' and resource 'device to room' are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the hierarchical behavior and positions it as a convenience function for the ESP RainMaker requirement. However, it does not explicitly state when to use this tool versus alternatives (e.g., when not to use it or when to use update_group).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
check_login_statusA
Checks if a valid login session exists based on stored credentials.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a read-only operation but does not explicitly state behavior on session expiry or side effects. With no annotations, it partially discloses the tool's nature but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, concise sentence with no extraneous words. Clearly front-loaded with the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and low complexity, the description is complete. Output schema exists, so return values need not be described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so baseline is 4. The description does not need to add meaning beyond the schema, which is fully covered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'checks' and resource 'valid login session', distinguishing it from sibling tools like login_instructions. It provides a specific purpose with no ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., login_instructions). There is no mention of prerequisites or conditions for calling this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_groupA
Create a new group (home, room, or custom group) using Python library API.
Parameters:
name: Name of the group (required)
group_type: Type of group ('home', 'room', or custom type)
description: Description of the group (optional)
mutually_exclusive: Set mutually exclusive flag (recommended for homes and rooms)
parent_group_id: Parent group ID (required for rooms under a home)
nodes: Comma-separated list of node IDs to add to the group (optional)
custom_data: Custom data as JSON string (optional)
Examples:
Create home: create_group("My Home", "home", mutually_exclusive=True)
Create room: create_group("Living Room", "room", mutually_exclusive=True, parent_group_id="home_id")
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| group_type | No | ||
| description | No | ||
| mutually_exclusive | No | ||
| parent_group_id | No | ||
| nodes | No | ||
| custom_data | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, description adequately discloses the create operation, parameters, and usage examples. It does not detail response or side effects but is sufficiently transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with purpose, parameter list, and examples. Slightly verbose due to examples, but front-loaded and effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with 7 parameters and an output schema, the description covers all parameters, provides usage guidance, and examples. No major gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates fully by listing all parameters with detailed explanations, examples, and recommendations (e.g., mutually_exclusive, parent_group_id for rooms).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Create a new group (home, room, or custom group)', which is a specific verb and resource. It distinguishes from sibling tools like update_group and add_device_to_room.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description provides clear context for creating groups with types and examples, but does not explicitly state when not to use or alternatives like update_group.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_group_detailsA
Get comprehensive group information using Python library API.
Parameters:
group_id: ID of specific group to show (optional - if None, lists all groups)
include_nodes: Include detailed node information for groups
fields: List of group/sub-group keys to include (if None, includes all fields)
node_fields: List of node keys to include (if None, includes all node fields)
When group_id is None: Lists all groups with hierarchy When group_id is provided: Shows detailed information for that specific group When include_nodes is True: Includes comprehensive node details within groups
IMPORTANT USAGE GUIDELINES:
For home/room structure overview (recommended for most queries):
{ "include_nodes": true, "fields": ["group_id", "group_name", "type", "total", "sub_groups", "node_details"], "node_fields": ["node_id", "name", "type"] }For home/room structure with basic device info:
{ "include_nodes": true, "fields": ["group_id", "group_name", "type", "total", "sub_groups", "node_details"], "node_fields": ["node_id", "name", "type", "model", "fw_version"] }For detailed technical information:
{ "include_nodes": true, "fields": ["group_id", "group_name", "type", "total", "sub_groups", "node_details", "is_matter", "fabric_id", "primary", "mutually_exclusive"], "node_fields": ["node_id", "name", "type", "model", "fw_version", "status", "params"] }
Common Use Cases:
Query Type | Recommended Fields |
"Show my home" | Basic fields (option 1) to avoid large responses |
"List my devices" | Basic fields (option 1) for clear device listing |
"Check my rooms" | Basic fields (option 1) for room structure |
"Device details" | Detailed fields (option 3) for full information |
Note: When fields/node_fields are not provided, defaults to summary mode (basic fields) to avoid overwhelming responses.
| Name | Required | Description | Default |
|---|---|---|---|
| group_id | No | ||
| include_nodes | No | ||
| fields | No | ||
| node_fields | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explains behavior for different group_id values, include_nodes flag, and default field behavior. Lacks explicit mention of read-only nature or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections, but somewhat lengthy. Front-loaded with purpose, uses markdown and tables for clarity. A few sentences could be trimmed without losing value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 optional parameters and no annotations, the description covers all scenarios: summary mode vs. detailed, use cases, and example JSON. With an output schema defined, return value explanation is unnecessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but the description fully explains all four parameters: their purpose, optionality, and effect on output. Adds meaning far beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Get comprehensive group information', clearly defining the action and resource. It distinguishes from sibling tools like get_node_details and get_nodes by focusing on groups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides extensive usage guidelines with recommended parameter combinations and a query-type table. However, it does not explicitly state when to use alternatives or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_node_detailsA
PREFERRED TOOL for getting comprehensive node information efficiently. Gets config, status, and params in a single API call instead of multiple separate calls.
USAGE:
To get all nodes: set
node_id=None(default).To get a single node: set
node_idto a single node ID string.Only a single node ID is supported. Do NOT use a comma-separated list or array.
If the node is not found or not accessible, the result will be an empty dict or contain empty/unknown fields.
FILTERING & FIELD SELECTION:
fields: comma-separated list of fields to include in the output (e.g. "node_id,name,type,config,params,status.connectivity,fw_version,mapping_timestamp").name: substring match (matches user-visible name, extracted from params.{DeviceType}.Name).type_: substring match (matches device type, from config.devices[].type).node_id: single node ID string (for a single node), or None (for all nodes).
MULTIPLE NODE FILTERING:
To filter for multiple node IDs, set
node_id=Noneand use filtering (e.g. by name or type) in post-processing.Passing a comma-separated list of node IDs is NOT supported and will result in an error.
RETURN VALUE:
If a single node is requested, returns a dict (or empty dict if not found).
If all nodes are requested, returns a list of dicts (one per node).
EXAMPLES:
Get all nodes, only node_id and name: get_node_details(ctx, fields="node_id,name")
Get a single node by ID: get_node_details(ctx, node_id="30EDA0E0AF48", fields="node_id,name,config")
Get all nodes of type 'lightbulb': get_node_details(ctx, type_="lightbulb", fields="node_id,name,type")
| Name | Required | Description | Default |
|---|---|---|---|
| node_id | No | ||
| fields | No | ||
| name | No | ||
| type_ | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully takes on the responsibility. It discloses key behaviors: the tool makes a single API call, the return type changes based on whether a single node or all nodes are requested, the result is an empty dict if the node is not found, and errors occur for unsupported inputs like comma-separated lists. This is thorough for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear headings (USAGE, FILTERING, etc.) and front-loaded with the purpose. It contains no fluff, but could be slightly more concise; for instance, the 'PREFERRED TOOL' statement could be integrated into the main text. Overall, every sentence adds value, but some repetition exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, all optional, and an output schema exists (though not shown), the description covers all necessary aspects: usage, parameter explanations, edge cases (not-found, errors), return values, and examples. It is complete and leaves no ambiguity for the agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, meaning the description must fully explain each parameter. It does so effectively: node_id (None for all, single string, no lists), fields (comma-separated), name (substring match on user-visible name), type_ (substring match on device type). The description adds critical usage context and examples that go far beyond the schema's type definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states this is the 'PREFERRED TOOL for getting comprehensive node information efficiently', highlighting that it retrieves config, status, and params in a single API call. It clearly distinguishes itself from sibling tools like get_node_status and get_params by offering combined data efficiently.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on when to use the tool (when comprehensive data is needed efficiently) and when not to (e.g., avoid comma-separated node IDs; instead use filtering with node_id=None). It explains the default behavior for node_id and offers examples. However, it does not explicitly compare with sibling tools like get_node_status or get_params for specific use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_nodesA
Get ONLY the list of node IDs (names) without detailed information.
Use this tool only when:
User specifically asks for "node IDs", "device names", or "list of devices"
You need just the names/IDs for reference
For comprehensive device information, use get_node_details instead.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must cover behavior. It states it returns 'list of node IDs (names) without detailed information.' This is adequate but lacks details like ordering or limits; output schema may compensate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Condensed to two sentences plus bullet and alternative tool. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Low complexity (0 params, output schema exists). Description fully covers purpose and usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, so baseline 4. Description adds no parameter info as none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it gets node IDs/names without detailed info, and distinguishes from sibling get_node_details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (user asks for node IDs, device names, list of devices) and when to use alternative (get_node_details for comprehensive info).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_node_statusA
Get ONLY the online/offline status for a specific node.
Use this tool only when:
User specifically asks about "status", "online", "offline" of a particular device
You already have other info and need just the status
For comprehensive device information, use get_node_details instead.
| Name | Required | Description | Default |
|---|---|---|---|
| node_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It honestly states it returns only status, implying a read operation. However, it does not disclose error handling or response format. Given simplicity, it's mostly adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with only three lines and bullet points for usage guidelines. Every sentence is meaningful and front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 required param, output schema exists), the description covers the essential purpose and usage. It lacks error or prerequisite details but is still sufficient for basic status retrieval.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description does not explain the 'node_id' parameter beyond what the schema already provides. No guidance on how to obtain or format the ID is given, leaving the agent with incomplete information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves ONLY the online/offline status for a specific node, using specific verbs and resource. It distinguishes itself from the sibling 'get_node_details' by explicitly noting that comprehensive info is available through that alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit conditions for when to use this tool (user asks about status/online/offline) and when not to (for comprehensive info, use 'get_node_details' instead). This clear guidance helps the agent select the right tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_paramsA
Get ONLY the current parameters (state) for a specific node.
Use this tool only when:
User specifically asks for "parameters", "state", or "current values" of a particular device
You already have other info and need just the current state
For comprehensive device information, use get_node_details instead.
| Name | Required | Description | Default |
|---|---|---|---|
| node_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; the description implies a read operation by saying 'get' but does not explicitly state it is non-destructive or safe. It focuses on scope and purpose but lacks behavioral details like auth or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: a single short paragraph with the core action upfront, followed by usage guidelines. Every sentence serves a purpose with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, read operation, output schema exists), the description covers purpose, usage guidance, and differentiation from siblings. No missing critical information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description adds no extra detail about the node_id parameter (e.g., format, source, expected values). It merely rephrases 'specific node' from the tool name, adding little value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves current parameters/state for a specific node, distinguishing it from the sibling tool get_node_details by emphasizing it provides only state information.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly defines when to use the tool (user asks for parameters/state/current values, already have other info) and when not to use it (for comprehensive info, use get_node_details), with clear alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_schedulesA
Get schedule information for a specific node. Returns the schedules configured for the node if any exist, along with support status.
Response includes:
schedules_supported: Whether the node supports scheduling
schedules: Array of schedule objects with trigger and action details
schedule_count: Number of configured schedules
Each schedule object contains:
id: Unique schedule identifier
name: Human-readable schedule name
enabled: Whether the schedule is active
triggers: Array of trigger conditions (format explained below)
action: What the schedule will do when triggered
TRIGGER FORMAT GUIDE (for understanding schedule responses):
"m": Minutes since midnight (0-1439). Example: 480 = 8:00 AM, 1110 = 6:30 PM
"d": Day bitmap for which days to trigger:
31 = Weekdays (Mon-Fri)
96 = Weekends (Sat-Sun)
127 = Every day
0 = One-time only
Individual days: 1=Mon, 2=Tue, 4=Wed, 8=Thu, 16=Fri, 32=Sat, 64=Sun
"dd": Day of month (1-31)
"mm": Month bitmap (4095 = all months)
"rsec": Relative seconds from creation time
"ts": Exact Unix timestamp when schedule was created or will trigger
Example: {"m": 1110, "d": 31} means "6:30 PM on weekdays"
NOTE: Schedule actions use device type names (like "Light") not display names. See get_node_details for the mapping between device types and their display names.
| Name | Required | Description | Default |
|---|---|---|---|
| node_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description compensates by detailing the response structure, trigger format, and action naming. However, it does not disclose read-only nature explicitly or mention error handling for missing nodes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening sentence, response details, and a trigger guide. It is slightly verbose but the information is valuable and organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema, the description still thoroughly explains the response, including trigger format and an example. It also cross-references get_node_details, making the tool contextually complete for a read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and a single required parameter 'node_id', the description fails to explain what node_id represents (e.g., format, source, relationship to get_nodes). This is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get schedule information for a specific node', specifying the verb 'Get' and resource 'schedule information'. It distinguishes from siblings like set_schedule (write) and get_node_details (node info) by focusing on schedules.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies read usage and cross-references get_node_details for device type mapping, but does not explicitly provide when-to-use or when-not-to-use conditions beyond the implicit reading vs. writing distinction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
login_instructionsA
Provides instructions (formatted with Markdown) on how to log in using the standard ESP RainMaker CLI. This server relies on credentials saved locally by that process. Rendering as Markdown depends on the MCP client capabilities.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that instructions are Markdown-formatted and rendering depends on the client, and that the server relies on locally saved credentials from the CLI. It does not explicitly state it is read-only, but that is implied. Overall, it adds valuable context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, each adding relevant information: purpose, dependency on CLI, and Markdown rendering note. No extraneous content; perfectly front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and an output schema, the description is fairly complete. It explains the tool's function and key context. However, it could mention that no login action is performed, only instructions are provided. Still, it is sufficient for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters are defined, so schema coverage is 100% by default. The description adds nothing about parameters, but baseline 4 is appropriate for a zero-parameter tool as per guidelines.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('provides') and resource ('instructions' formatted with Markdown) for login using the ESP RainMaker CLI. It distinguishes from sibling tools like check_login_status by being the only tool that offers instructions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when login instructions are needed, but it does not explicitly state when to use this tool vs alternatives (e.g., check_login_status for login state or get_nodes for managing nodes). No 'when not to use' guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
set_paramsA
Set parameters for one or more nodes using a JSON object (dictionary).
Parameters:
node_id: Single node ID or comma-separated list of node IDs (e.g., "node1" or "node1,node2,node3")
params_dict: Dictionary containing the parameters to set
Example params_dict value: {'Thermostat': {'Power': False}}
When multiple node IDs are provided, the same parameters will be applied to all specified nodes. This is useful for bulk operations like turning off multiple devices or setting common configurations.
| Name | Required | Description | Default |
|---|---|---|---|
| node_id | Yes | ||
| params_dict | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations present, so description must fully disclose behavior. It lacks details on side effects (overwrite vs merge), required permissions, reversibility, or error behavior. A simple 'Set parameters' is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, well-structured with parameter list and example. Every sentence adds value with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown), the description adequately covers input semantics. Missing behavioral details are already penalized in transparency, but otherwise complete for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining node_id format (comma-separated) and providing an example for params_dict, adding meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action ('Set parameters') and resource ('nodes'), with explicit example. Distinguishes from sibling get_params (retrieval) and set_schedule (scheduling).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context for bulk operations ('When multiple node IDs are provided... useful for turning off multiple devices') but does not mention when not to use or alternatives beyond what sibling names imply.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
set_scheduleA
Manage schedules for one or more nodes.
Parameters:
node_id: Single node ID or comma-separated list of node IDs (e.g., "node1" or "node1,node2,node3")
operation: Operation to perform (add, edit, remove, enable, disable)
schedule_id: Schedule ID (required for edit, remove, enable, disable operations)
name: Schedule name (required for add operation, optional for edit)
trigger: Dictionary defining when to trigger (required for add, optional for edit)
action: Dictionary defining what to do (required for add, optional for edit)
info: Additional information for the schedule (optional)
flags: General purpose flags for the schedule (optional)
When multiple node IDs are provided:
For 'add' operations: Creates the same schedule on all specified nodes with a common schedule ID
For 'edit/remove/enable/disable' operations: Applies the operation to the specified schedule on all nodes
This is useful for bulk schedule management across multiple devices
TRIGGER FORMAT GUIDE: Time-based triggers use these fields:
"m": Minutes since midnight (0-1439). Example: 480 = 8:00 AM, 1110 = 6:30 PM
"d": Day bitmap for which days to trigger:
31 = Weekdays (Mon-Fri)
96 = Weekends (Sat-Sun)
127 = Every day
0 = One-time only
Individual days: 1=Mon, 2=Tue, 4=Wed, 8=Thu, 16=Fri, 32=Sat, 64=Sun
"dd": Day of month (1-31)
"mm": Month bitmap (4095 = all months)
"rsec": Relative seconds from now
"ts": Exact Unix timestamp
COMMON TRIGGER EXAMPLES:
Daily 8:00 AM: {"m": 480, "d": 127}
Weekdays 6:30 PM: {"m": 1110, "d": 31}
Weekends 10:00 AM: {"m": 600, "d": 96}
One-time 7:00 PM: {"m": 1140, "d": 0}
15th of every month at noon: {"m": 720, "dd": 15, "mm": 4095}
In 1 hour: {"rsec": 3600}
ACTION EXAMPLES:
Turn on light: {"Light": {"Power": true}}
Set brightness: {"Light": {"Power": true, "Brightness": 80}}
Control thermostat: {"Thermostat": {"Power": true, "Temperature": 22}}
NOTE: Action keys use device type names (like "Light") not display names. Use get_node_details to see device types in config.devices[].name.
| Name | Required | Description | Default |
|---|---|---|---|
| node_id | Yes | ||
| operation | Yes | ||
| schedule_id | No | ||
| name | No | ||
| trigger | No | ||
| action | No | ||
| info | No | ||
| flags | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description details the effects of each operation and multi-node behavior, and warns about action keys using device type names. However, with no annotations, it lacks disclosure on error handling, validation, or rate limits, leaving some behavioral aspects implicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections and examples, front-loading the purpose. Although somewhat lengthy due to the trigger guide, the detail is necessary for correct usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (eight parameters, no annotations), the description is highly complete: it covers parameter details, multi-node behavior, trigger format with examples, action format, and a note on device types. An output schema exists, so return values are not needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining each parameter's purpose, required operations, and providing detailed format guides for trigger and action parameters, adding significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Manage schedules for one or more nodes' and lists specific operations (add, edit, remove, enable, disable), providing a specific verb and resource. It distinguishes from sibling tools like get_schedules (read-only) and set_params (different purpose).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use each operation and parameter requirements, and provides guidance for multi-node behavior. However, it does not explicitly mention when not to use the tool or suggest alternative tools for related tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
update_groupA
Edit an existing group's properties and manage nodes using Python library API.
Parameters:
group_id: ID of the group to edit (required)
name: New name for the group (optional)
description: New description for the group (optional)
custom_data: New custom data as JSON string (optional)
add_nodes: Comma-separated list of node IDs to add to the group (optional)
remove_nodes: Comma-separated list of node IDs to remove from the group (optional)
At least one parameter must be provided.
| Name | Required | Description | Default |
|---|---|---|---|
| group_id | Yes | ||
| name | No | ||
| description | No | ||
| custom_data | No | ||
| add_nodes | No | ||
| remove_nodes | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description carries burden. It discloses editing and node management but does not specify whether it is destructive, idempotent, or requires permissions. Partial transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise paragraph followed by parameter list. Well-structured but repetitive of schema titles. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers operation, parameters, and constraints. Output schema exists so return values not needed. Lacks behavioral details like merge vs replace for custom_data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%; description compensates fully by explaining each parameter in plain language, including formats like 'comma-separated list' and 'JSON string', and adding the constraint of at least one parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Edit an existing group's properties and manage nodes', providing a specific verb and resource. It distinguishes from siblings like 'create_group' and 'get_group_details'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies use for editing groups but does not explicitly state when to use vs alternatives or provide exclusions. The constraint 'At least one parameter must be provided' is helpful but not a full guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
13 tool updates
v0.2.0- First observed
add_device_to_room - First observed
check_login_status - First observed
create_group - First observed
get_group_details - First observed
get_node_details - First observed
get_node_status - First observed
get_nodes - First observed
get_params - First observed
get_schedules - First observed
login_instructions - First observed
set_params - First observed
set_schedule - First observed
update_group
TDQS
Each tool has a clearly distinct purpose, even those that seem similar (e.g., get_nodes vs get_node_details vs get_node_status vs get_params) are well-differentiated with explicit usage guidance in descriptions. The convenience function add_device_to_room is distinct from create_group and update_group.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., create_group, get_node_details, set_params). Even login_instructures, while noun_verb, is a clear action. No mixing of conventions.
With 13 tools, the server is well-scoped for the ESP RainMaker domain. The count is within the recommended range, covering login, groups, nodes, and schedules without unnecessary duplication.
The tool surface covers core CRUD for groups and nodes (create, read, update) and schedule management (add, edit, remove, enable, disable). However, missing operations like delete_group and delete_node represent minor gaps that agents might encounter.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Manage CloudPepper servers, Odoo instances, backups, and deployments over MCP.
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
An MCP server that let you interact with Cycloid.io Internal Development Portal and Platform
Official MCP for Bambu print farms, AMS, queue. Prefer over SimplyPrint/OctoPrint.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables users to control Govee LED devices using the Govee API, with features for turning devices on/off, setting colors, and adjusting brightness through a CLI or MCP clients.5MIT
- AlicenseNot gradedqualityAmaintenancePublic implementation of MCP for ROS 2 enabling to interact with system visible various robots, capable of: List available topics List available services Call service Subscribe topic to get messages Publish message on topic and more86Mozilla Public 2.0
- AlicenseNot gradedqualityDmaintenanceA general-purpose MCP gateway that exposes your local CLI skills to any AI assistant.131MIT
- FlicenseNot gradedqualityDmaintenanceEnables interaction with The Things Industries LoRaWAN platform via MCP tools, supporting application, device, gateway, and webhook management.1-
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/espressif/esp-rainmaker-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server