STARWARCLOUD STARWAR.AI
返回市场
艾科瓦斯-mcp

艾科瓦斯-mcp

作者：ecovacs-ai17 星标更新：2025-04-29
安装使用来源：spider==github.com

项目介绍

清洁机器人控制MCP服务器

英文 中文

Ecovacs的核心API现在完全兼容MCP协议，使其成为世界上第一个支持MCP协议的清洁机器人服务提供商。

Ecovacs已经完成了四个核心API接口与MCP协议的集成，包括设备列表查询、清洁控制、充电控制以及工作状态查询。

作为世界上第一个支持MCP协议的清洁机器人服务提供商，Ecovacs MCP服务器发布后，智能代理开发者可以快速通过简单配置在大模型中接入机器人服务，实现查询、清洁、充电等功能。

在代理应用开发过程中调用机器人控制服务的门槛显著降低，代理应用的开发效率也得到了显著提升。

工具

设备列表查询

检索用户绑定的所有机器人的列表。

输入：

无参数

返回：

{
  "status": 0,
  "message": "成功",
  "data": [
    {
      "nickname": "机器人昵称",
    }
  ]
}

开始清洁

控制扫地机器人开始、暂停、恢复或停止清洁。

输入：

  • nickname：机器人昵称，用于搜索设备，支持模糊匹配
  • act：清洁行为
    • s：开始清洁
    • r：恢复清洁
    • p：暂停清洁
    • h：停止清洁

返回：

{
  "msg": "OK",
  "code": 0,
  "data": []
}

控制充电

控制机器人开始或停止充电。

输入：

  • nickname：机器人昵称，用于搜索设备
  • act：机器行为
    • go-start：开始充电
    • stopGo：结束充电

返回：

{
  "msg": "OK",
  "code": 0,
  "data": []
}

查询工作状态

查询当前机器人的工作状态。

输入：

  • nickname：机器人昵称，用于搜索设备

返回：

{
	"code": 0,
	"msg": "成功",
	"data": {
		"ctl": {
			"data": {
				"ret": "ok",
				"cleanSt": "h",
				"chargeSt": "正在充电",
				"stationSt": "i"
			}
		}
	}
}

状态码描述：

参数名称类型描述
CleanSt字符串清洁状态，请求成功时存在。S-清扫，p-暂停，h-空闲，goposition-前往指定位置，goposition pause-在指定点停止，findpet-寻找宠物，findpetpause-寻找宠物暂停，cruise-巡航，cruisepause-巡航暂停，buildmap-创建地图，buildmappause-创建地图暂停
ChargeSt字符串充电状态，请求成功时存在。G-正在充电，gp-充电暂停，i-空闲，sc-基座充电，wc-线充电，正在充电（包括SC和WC）
StationSt字符串基站状态，i-空闲，wash-清洗抹布，dry-干燥，drypause-干燥暂停，dust-集尘，dustpause-集尘暂停，clean-清洁基站，cleanpause-清洁基站暂停，wash-清洗抹布，washuse-清洗抹布暂停

安装

GitHub本地安装

git clone git@github.com:ecovacs-ai/ecovacs-mcp.git

uv add "mcp[cli]" mcp requests

uv run ecovacs_mcp/robot_mcp_stdio.py

PyPI

pip install ecovacs-robot-mcp

python3 -m ecovacs_robot_mcp

环境变量

  • ECO_API_KEY：API访问密钥，用于验证接口调用权限
  • ECO_API_URL：API主机地址
    • 中国大陆：https://open.ecovacs.cn
    • 非中国大陆：https://open.ecovacs.com

获取AK&删除AK

在选择两种方法（本地或SSE）之前，需要在Ecovacs开放平台控制台创建一个服务器端AK，以便调用机器人的API能力。

如果要取消授权，可以去Ecovacs开放平台控制台删除AK的授权。

Ecovacs开放平台（中国大陆）：https://open.ecovacs.cn

Ecovacs开放平台（非中国大陆）：https://open.ecovacs.com

<img src="images/img_v3_02lo_b450632b-9dbe-4cd9-aead-c625ad3458fg.jpg" alt="获取AK" width="600" />

配置

在任何MCP客户端（如Claude.app）中添加以下配置，并可能需要对某些客户端进行一些格式调整。

其中ECO_API_KEY是API的访问密钥，ECO_API_URL是API的主机地址。

  • 使用uvx
{
  "mcpServers": {
    "ecovacs_mcp": {
      "command": "uvx",
      "args": ["ecovacs-robot-mcp"],
      "env": {
        "ECO_API_KEY": "您的AK...........",
        "ECO_API_URL": "https://open.ecovacs.cn" // 如果是非中国内地，配置为 https://open.ecovacs.com
      }
    }
  }
}
  • 使用pip安装
{
  "mcpServers": {
    "ecovacs_mcp": {
      "command": "python",
      "args": ["-m", "ecovacs-robot-mcp"],
      "env": {
          "ECO_API_KEY": "您的AK...........",
          "ECO_API_URL": "https://open.ecovacs.cn" // 如果是非中国内地，配置为 https://open.ecovacs.com
      }
    }
  }
}

使用示例（Claude列）

打开桌面版Claude的设置，切换到开发者选项，点击编辑配置，并使用任何IDE打开配置文件。

<img src="images/img_v3_02lm_ac10ff15-8764-4ad3-906c-5c8433a9e5eg.jpg" alt="Claude设置界面" width="600" /> <img src="images/img_v3_02lm_2ced9293-af22-4d9f-a70c-337643a93c7g.jpg" alt="Claude配置文件" width="600" />

在配置文件中添加以下配置，ECO_API_KEY是访问Ecovacs开放平台API的AK此页面申请获取：

{
    "mcpServers": {
        "ecovacs_mcp": {
            "command": "python3",
            "args": ["-m", "ecovacs_robot_mcp"],
            "env": {
                "ECO_API_KEY": "您的AK......",
                "ECO_API_URL": "https://open.ecovacs.cn"// 如果是非中国内地，配置为 https://open.ecovacs.com
            }
        }
    }
}

重启Claude，设置面板已成功加载Ecovacs机器人MCP服务器。软件主界面对话框中有4个可用的MCP工具，点击查看详情。

<img src="images/img_v3_02lm_e1b700d6-9693-4448-8acf-d622f28b3b3g.jpg" alt="Claude MCP工具" width="600" />

效果

接下来，您可以提问以验证Ecovacs机器人助手的能力。

<img src="images/img_v3_02lm_2f3b431a-c289-4476-8a24-1ff1a231aadg.jpg" alt="Claude交互效果" width="600" />

使用示例（光标显示）

进入光标设置界面配置SSE连接

<img src="images/doc_1743660020811_d2b5c.6bec4f04.png" alt="Cursor设置界面" width="600" />

添加新的MCP服务器配置

  • 中国大陆
{
  "mcpServers": {
    "robot_control_server": {
      "url": "https://mcp-open.ecovacs.cn/sse?ak=您的AK"
      // 对于中国大陆以外的地区，配置为 https://mcp-open.ecovacs.com/sse?ak=您的AK
    }
  }
}
  • 非中国大陆
{
  "mcpServers": {
    "robot_control_server": {
      "url": "https://mcp-open.ecovacs.com/sse?ak=您的AK"
    }
  }
}

返回光标设置界面检查MCP服务工具的状态

<img src="images/20250423-175131.0caa52fa.jpg" alt="Cursor MCP服务状态" width="600" />

选择配置光标的大型模型以获得更好的服务体验。建议选择claude-3.7-sonnet

<img src="images/doc_1743660126834_d2b5c.fc9da8f3.png" alt="Cursor模型配置" width="600" />

模型交互模式：选择代理模式

<img src="images/doc_1743660181250_d2b5c.1d9a47eb.png" alt="Cursor交互模式" width="600" />

效果

<img src="images/img_v3_02lm_f5094f2f-7cf3-4ee4-a5f9-ae29b746175g.jpg" alt="Cursor交互模式" width="600" />

许可证

MIT © ecovacs

反馈

如果您在使用Ecovacs机器人MCP服务器时遇到任何问题，请随时联系我们issue或者联系我们，我们也欢迎每一个积极的PR`，非常感谢您的支持和贡献 ❤️

联系信息

邮件：pei.zhou@ecovacs.com

微信：

<img src="images/img_v3_02lm_d2a67ba9-6fa2-4f96-9d37-09f8d8b8e21g.png" alt="微信二维码" width="200" />

更新

版本功能描述更新日期
V1.0Ecovacs MCP服务器正式发布2025年4月24日