项目简介

该项目是科沃斯官方发布的基于 Model Context Protocol (MCP) 的服务器实现，旨在帮助大语言模型（LLM）客户端（如Claude、Cursor等）通过标准化的方式接入和控制科沃斯扫地机器人设备。它将科沃斯开放平台的API封装为MCP工具，极大地简化了LLM应用开发者集成机器人控制功能的流程。

主要功能点

该MCP服务器提供了以下主要功能，允许大语言模型直接调用：

查询设备列表： 获取用户账号下绑定的所有科沃斯扫地机器人设备列表及其昵称。
启动清扫： 控制指定的扫地机器人开始、暂停、恢复或停止清扫任务。
控制回充： 控制指定的扫地机器人开始或停止返回充电座。
查询工作状态： 获取指定扫地机器人当前的清扫状态、充电状态和基站状态等详细信息。

安装步骤

您可以选择以下任一方式安装并运行MCP服务器：

通过GitHub本地安装：
- 克隆仓库到本地：'git clone [email protected]:ecovacs-ai/ecovacs-mcp.git'
- 进入项目目录：'cd ecovacs-mcp'
- 使用'uv'或'pip'安装依赖（建议使用'uv'）：
```
# 如果没有安装uv，先安装：pip install uv
uv add "mcp[cli]" mcp requests
```
  或者使用pip: 'pip install mcp requests'
- 运行服务器（Stdio模式）：'uv run ecovacs_mcp/robot_mcp_stdio.py' 或 'python3 ecovacs_mcp/robot_mcp_stdio.py'
通过PyPI安装：
- 安装库：'pip install ecovacs-robot-mcp'
- 运行服务器（Stdio模式）：'python3 -m ecovacs_robot_mcp'

服务器配置

MCP服务器需要您的科沃斯开放平台API密钥（AK）和API地址才能正常工作。这些信息需要通过环境变量提供给服务器进程。

'ECO_API_KEY': 您的API访问密钥。请在科沃斯开放平台控制台申请。
'ECO_API_URL': 科沃斯API的HOST地址。中国内地用户配置为 'https://open.ecovacs.cn'，非中国内地用户配置为 'https://open.ecovacs.com'。

重要： MCP服务器通常由MCP客户端（大语言模型应用）启动和管理。您需要在您使用的MCP客户端（如Claude、Cursor等）的设置或配置文件中，添加对该服务器的引用。

客户端配置通常包含：

服务器名称: 为您的MCP服务器指定一个唯一的名称（例如：'ecovacs_mcp' 或 'robot_control_server'）。
连接方式:
- Stdio模式: 配置客户端启动该服务器进程的命令 (command) 和参数 (args)。您需要在客户端的环境变量设置中，将 'ECO_API_KEY' 和 'ECO_API_URL' 传递给服务器进程。
  - 例如，使用 'uvx' 启动： command为 'uvx'，args为 '["ecovacs-robot-mcp"]'。
  - 例如，使用 'python' 启动： command为 'python'，args为 '["-m", "ecovacs-robot-mcp"]'。
- SSE模式: 如果服务器提供SSE接口，您可能需要配置服务器的SSE URL，并在URL参数中包含AK，例如：'https://open.ecovacs.cn/sse?ak=YOUR_AK'。

请参考您使用的MCP客户端的具体文档来完成配置。

基本使用方法

配置完成后，启动您的MCP客户端（大语言模型应用）。如果配置正确，客户端会检测到科沃斯机器人MCP服务器并展示其提供的工具能力。

您现在可以直接在与大模型的对话中提出与扫地机器人相关的自然语言请求，例如：

“查询一下我的扫地机器人列表。”
“让我的扫地机器人开始清扫。”
“让客厅里的机器人回充。”
“我的机器人现在是什么状态？”

大模型将根据您的请求，自动调用对应的MCP工具来执行操作或获取信息。

关键词

信息