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 文件中指定的條款進行授權。