Ecovacs Robot Vacuum Control
Control Ecovacs robot vacuums through the official Ecovacs MCP server. This is the first official MCP integration for robotic cleaning devices.
Prerequisites
- - API Key (
ECO_API_KEY) from open.ecovacs.com uvx (recommended) or python3 with ecovacs-robot-mcp installed- A robot registered in the Ecovacs mobile app, bound to the same account
MCP Server Configuration
The MCP server entry should look like this in your settings:
CODEBLOCK0
Regional endpoints:
- - International: INLINECODE4
- China mainland: INLINECODE5
MCP Tools Reference
The server exposes four tools. All device operations use a nickname parameter that supports fuzzy matching — you don't need the exact name.
getdevicelist
Lists all robots bound to the account. No parameters.
Always call this first to discover available robots and their nicknames.
start_cleaning
Controls cleaning operations.
| Parameter | Values | Description |
|---|
| INLINECODE7 | string | Robot name (fuzzy match) |
| INLINECODE8 |
s | Start cleaning |
|
act |
p | Pause cleaning |
|
act |
r | Resume cleaning |
|
act |
h | Stop cleaning |
control_recharging
Controls dock/charging operations.
| Parameter | Values | Description |
|---|
| INLINECODE16 | string | Robot name (fuzzy match) |
| INLINECODE17 |
go-start | Return to charging dock |
|
act |
stopGo | Cancel return to dock |
queryworkingstatus
Returns real-time robot state. No input besides
nickname. Returns three status fields:
- -
cleanSt — Cleaning state (sweeping, mopping, paused, idle, mapping) chargeSt — Charging state (returning to dock, docking, charging, idle)stationSt — Dock station state (washing mop, drying, dust collection, idle)
Operating Guidance
- 1. Always list devices first — call
get_device_list before any operation to get the correct nickname. Cache the nickname for the session. - Confirm actions — after starting or stopping cleaning, call
query_working_status to verify the command took effect. - Standard workflows:
-
Start cleaning: list devices →
start_cleaning (act:
s) → check status
-
Send home: control_recharging (act:
go-start) → check status
-
Pause and resume: start_cleaning (act:
p) → later (act:
r)
- 4. Natural language mapping:
- "vacuum the house" / "clean the floor" / "start cleaning" →
start_cleaning act:
s
- "send it back" / "dock" / "go home" / "charge" →
control_recharging act:
go-start
- "stop" / "pause" →
start_cleaning act:
p or
h
- "what's it doing?" / "is it charging?" → INLINECODE41
Troubleshooting
- - No devices found — robot must be set up in the Ecovacs app and bound to the same account used for the API key
- Authentication errors — verify
ECO_API_KEY is correct and ECO_API_URL matches your region - Server won't start — ensure
uvx is available (pip install uv), or install directly: INLINECODE46
Ecovacs 机器人吸尘器控制
通过官方 Ecovacs MCP 服务器控制 Ecovacs 机器人吸尘器。这是首个针对清洁机器人的官方 MCP 集成方案。
前置条件
- - 从 open.ecovacs.com 获取 API 密钥 (ECOAPI_KEY)
- uvx（推荐）或已安装 ecovacs-robot-mcp 的 python3
- 已在 Ecovacs 移动应用中注册并与同一账号绑定的机器人
MCP 服务器配置
MCP 服务器入口在设置中应如下所示：
json
{
ecovacs_mcp: {
command: uvx,
args: [--from, ecovacs-robot-mcp, python, -m, ecovacsrobotmcp],
env: {
ECOAPIKEY: 你的API密钥,
ECOAPIURL: https://open.ecovacs.com
}
}
}
区域端点：
- - 国际版：https://open.ecovacs.com
- 中国大陆版：https://open.ecovacs.cn
MCP 工具参考
服务器提供四个工具。所有设备操作均使用支持模糊匹配的 nickname 参数——无需使用确切名称。
getdevicelist
列出与账号绑定的所有机器人。无需参数。
始终先调用此工具以发现可用机器人及其昵称。
start_cleaning
控制清洁操作。
| 参数 | 值 | 描述 |
|---|
| nickname | 字符串 | 机器人名称（模糊匹配） |
| act |
s | 开始清洁 |
| act | p | 暂停清洁 |
| act | r | 恢复清洁 |
| act | h | 停止清洁 |
control_recharging
控制充电座/充电操作。
| 参数 | 值 | 描述 |
|---|
| nickname | 字符串 | 机器人名称（模糊匹配） |
| act |
go-start | 返回充电座 |
| act | stopGo | 取消返回充电座 |
queryworkingstatus
返回机器人实时状态。除 nickname 外无需其他输入。返回三个状态字段：
- - cleanSt — 清洁状态（扫地、拖地、暂停、待机、建图）
- chargeSt — 充电状态（返回充电座、对接中、充电中、待机）
- stationSt — 充电座状态（洗拖布、烘干、集尘、待机）
操作指南
- 1. 始终先列出设备 — 在任何操作前调用 getdevicelist 获取正确的昵称。在会话中缓存该昵称。
- 确认操作 — 启动或停止清洁后，调用 queryworkingstatus 验证命令已生效。
- 标准工作流程：
-
开始清洁： 列出设备 → start_cleaning（act: s）→ 检查状态
-
返回充电： control_recharging（act: go-start）→ 检查状态
-
暂停和恢复： start_cleaning（act: p）→ 稍后（act: r）
- 4. 自然语言映射：
- 打扫房子 / 清洁地板 / 开始清洁 → start_cleaning act: s
- 让它回去 / 回充 / 回家 / 充电 → control_recharging act: go-start
- 停止 / 暂停 → start_cleaning act: p 或 h
- 它在做什么？ / 它在充电吗？ → query
workingstatus
故障排除
- - 未找到设备 — 机器人必须在 Ecovacs 应用中完成设置，并与用于 API 密钥的同一账号绑定
- 认证错误 — 验证 ECOAPIKEY 是否正确，以及 ECOAPIURL 是否与您的区域匹配
- 服务器无法启动 — 确保 uvx 可用（pip install uv），或直接安装：pip install ecovacs-robot-mcp
