Esp Rainmaker MCP

🚀 ESP RainMaker MCP 服务器

围绕 esp-rainmaker-cli Python 库构建的 模型上下文协议 (MCP) 服务器封装，让 AI 助手能够通过官方 CLI 操控你的 ESP RainMaker 设备。

本项目为 esp-rainmaker-cli Python 库提供了一层 模型上下文协议 (MCP) 服务器封装。它允许兼容 MCP 的客户端（如 LLM 或 Cursor、Claude Desktop、Windsurf 等应用）通过官方 CLI 与你的 ESP RainMaker 设备进行交互。

📖 模型上下文协议 (MCP) 简介

模型上下文协议 (MCP) 是一个标准化框架，使 AI 系统能够以统一的方式与外部工具、数据源和服务进行交互。该协议由 Anthropic 提出并被主流 AI 组织采用，MCP 就像硬件领域的 USB-C 一样，充当一个通用接口，实现跨平台的 seamless 集成。

✨ MCP 在 ESP RainMaker 中的核心优势

• 🔗 统一交互：MCP 允许 AI 模型使用自然语言提示访问和控制 IoT 设备，使交互更加直观、易用。
• ⚡ 实时控制：借助 MCP，用户可直接通过 AI 界面执行开关设备、调整设置、管理日程等操作。
• 🔒 本地服务器 + 云端控制：ESP RainMaker MCP 服务器在本地运行，凭证存储在你的机器上；而设备管理操作则通过 esp-rainmaker-cli 调用官方 ESP RainMaker 云 API 完成。

通过集成 MCP，ESP RainMaker 平台的能力得到进一步增强，让 Claude、Cursor、Windsurf 和 Gemini CLI 等工具能够高效、安全地管理 IoT 设备。

📋 前置要求

• Python：版本 3.10 或更高
• uv：uv Python 包管理器。安装说明请参阅 Astral 的 uv 文档。
• ESP RainMaker CLI 登录：你必须至少通过终端成功执行过一次标准的 esp-rainmaker-cli login 命令完成 ESP RainMaker 登录。本服务器依赖该过程保存的凭证。
• RainMaker 节点：需已添加到你的账户中，因为 MCP 服务器不支持设备入网 (onboarding)。

📦 安装指南

1. 克隆仓库

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

2. 使用 uv 安装依赖

该命令会将 esp-rainmaker-cli、mcp[cli] 以及 pyproject.toml 中列出的其他依赖项安装到由 uv 管理的虚拟环境中。

uv sync

（此操作假定已安装 uv）

3. 使用 esp-rainmaker-cli 登录 ESP RainMaker

uv run esp-rainmaker-cli login

⚠️ 注意

出于安全考虑，不支持在 MCP 内直接使用用户名/密码登录。请先完成标准的 CLI 登录流程。

⚙️ 客户端配置

要将本项目作为 MCP 服务器添加到支持的 MCP 客户端（Cursor、Claude Desktop、Windsurf 和 Gemini CLI）中，你需要将相同的 JSON 配置添加到每个客户端的配置文件中。所有客户端的配置完全相同：

MCP 服务器配置（适用于所有客户端）

在所有 MCP 客户端中使用以下 JSON 配置：

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

⚠️ 重要提示

请将 <absolute_path_to_repo>/server.py 替换为你系统上克隆的 esp-rainmaker-mcp 目录中 server.py 文件的绝对路径。

🖱️ Cursor MCP 服务器设置

1. 打开 Cursor，点击右上角的设置（齿轮图标）。

2. 从设置菜单中导航到 "Tools & Integrations"。

3. 在集成部分点击 "MCP Tools"。

4. 点击 "New MCP Server" 添加新服务器。

5. 这将打开 mcp.json 文件。添加上面显示的 JSON 配置。

🤖 Claude Desktop MCP 服务器设置

1. 打开 Claude Desktop，前往 Settings -> Developer -> Edit Config。

2. 这将打开配置文件 (claude_desktop_config.json)。添加上面显示的 JSON 配置。

3. 保存更改并重启 Claude Desktop 以应用新设置。

🏄 Windsurf MCP 服务器设置

1. 打开 Windsurf，在聊天输入框下方找到锤子形状的图标。

2. 点击锤子图标，从选项中选择 "Configure"。这将打开插件窗口。

3. 点击 "View raw config"，将显示 ~/.codium/windsurf/mcp_config.json 文件。

4. 将上面显示的 JSON 配置添加到该文件中。

5. 保存更改，并点击聊天文本窗口下方的 "Refresh" 以加载 ESP RainMaker MCP 工具。

💎 Gemini CLI MCP 服务器设置

1. 找到你的 Gemini CLI 设置文件。在 macOS 上，通常位于 ~/.gemini/settings.json。

2. 使用你偏好的文本编辑器打开 settings.json 文件。

3. 将上面显示的 JSON 配置添加到文件的 mcpServers 部分。如果该部分不存在，请按示例创建它。

4. 保存文件，若 Gemini CLI 正在运行则重启它。

💡 使用提示

这四个应用（Cursor、Claude Desktop、Windsurf 和 Gemini CLI）的配置完全相同，因此你可以对所有应用使用相同的 JSON 结构。

💡 使用提示

--with 参数确保 uv 在运行 mcp run 命令时包含所需的依赖项。

🔧 工作原理

本服务器充当桥梁。它使用 mcp 库处理模型上下文协议通信。当工具被调用时：

1. 它使用已安装的 esp-rainmaker-cli 库中的函数。
2. 库函数读取本地存储的认证令牌。
3. 它向 ESP RainMaker 云端发起必要的 API 调用。
4. 它通过 MCP 协议返回结果（或错误）。

🛠️ 可用工具

本 MCP 服务器暴露以下用于与 ESP RainMaker 交互的工具：

🔐 认证与配置

• login_instructions()：
  • 提供如何使用终端中标准的 esp-rainmaker-cli login 命令登录的说明（以 Markdown 格式呈现）。 本服务器依赖外部 CLI 的基于浏览器的登录流程来安全地存储凭证。 是否渲染为 Markdown 取决于 MCP 客户端的能力。
• check_login_status()：
  • 基于 esp-rainmaker-cli 在本地存储的凭证检查是否存在有效的登录会话。 确认服务器能否与 ESP RainMaker 后端通信。

🌐 节点管理

• get_nodes()：
  • 列出与已登录用户关联的所有节点 ID。
• get_node_details(node_id: str = None, fields: str = None, name: str = None, type_: str = None)：
  • 获取节点的详细信息，包括配置、状态和参数。
  • 支持过滤和字段选择：
    • fields：要包含的字段的逗号分隔列表（例如 "node_id,name,type,config,params,status.connectivity,fw_version,mapping_timestamp"）
    • name：子串匹配（来自 params 的用户可见名称）
    • type_：子串匹配（设备类型）
    • node_id：单个节点 ID（针对单个节点）或 None（针对所有节点）
  • 返回字典（单个节点）或字典列表（所有节点）。
  • 示例：

    get_node_details(ctx, fields="node_id,name,type")
    

• get_node_status(node_id: str)：
  • 获取指定节点 ID 的在线/离线连接状态。
• get_params(node_id: str)：
  • 获取设备的当前参数值。
• set_params(node_id: str, params_dict: dict)：
  • 为一个或多个设备设置参数。
  • node_id：单个 ID 或逗号分隔列表（例如 "light1,light2"）
  • params_dict：要设置的参数，例如 {"Light": {"Power": true}}

⏰ 日程管理

• get_schedules(node_id: str)：
  • 获取设备的日程。
• set_schedule(node_id: str, operation: str, ...)：
  • 管理设备日程。
  • operation："add"、"edit"、"remove"、"enable" 或 "disable"
  • 对于 add/edit：需提供 name、trigger 和 action
  • 常用触发器：
    • 每天上午 8 点：{"m": 480, "d": 127}
    • 工作日下午 6:30：{"m": 1110, "d": 31}
  • 示例动作：{"Light": {"Power": true}}

🏠 分组管理（家庭/房间层级）

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

  • 创建家庭或房间。
  • 必需：name、group_type（"home" 或 "room"）
  • 对于房间：需要 parent_group_id
  • 示例：create_group("Living Room", "room", parent_group_id="home_id")

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

  • 获取分组信息。若要获取所有分组，请使用 group_id=None。
  • 设置 include_nodes=True 以包含设备详情。
  • 返回：分组层级、成员和元数据。

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

  • 更新分组属性或管理设备。
  • 可选：name、description、add_nodes、remove_nodes
  • 示例：
    • 重命名：update_group("group_id", name="New Name")
    • 添加设备：update_group("group_id", add_nodes="light1,light2")

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

  • 将设备添加到房间（自动处理父分组）。
  • 示例：add_device_to_room("light1", "kitchen_id")

📄 许可证

本项目依据 LICENSE 文件中指定的条款进行授权。