Ecovacs MCP Server
Robot Vacuum Control MCP Server
English | 中文
Ecovacs core API now fully supports the MCP protocol, making it the world's first robot service provider compatible with the MCP protocol.
Ecovacs has completed the integration of 4 core API interfaces with the MCP protocol, including device list query, cleaning control, recharging control, and working status query.
As the world's first cleaning robot service provider to support the MCP protocol, after the release of Ecovacs MCP Server, AI agent developers only need simple configuration to quickly access robot services in large language models, enabling query, cleaning, recharging, and other capabilities.
This significantly lowers the threshold for calling robot control services during AI agent application development and greatly improves the development efficiency of AI agent applications.
Tools
Device List Query
Get a list of all robots bound to the user.
Input:
No parameters
Returns:
{
"status": 0,
"message": "success",
"data": [
{
"nickname": "Robot nickname",
}
]
}
Start Cleaning
Control the robot vacuum to start, pause, resume, or stop cleaning.
Input:
nickname: Robot nickname, used to find the device, supports fuzzy matchingact: Cleaning actions: Start cleaningr: Resume cleaningp: Pause cleaningh: Stop cleaning
Returns:
{
"msg": "OK",
"code": 0,
"data": []
}
Control Recharging
Control the robot to start or stop recharging.
Input:
nickname: Robot nickname, used to find the deviceact: Robot actiongo-start: Start rechargingstopGo: Stop recharging
Returns:
{
"msg": "OK",
"code": 0,
"data": []
}
Query Working Status
Query the robot's current working status.
Input:
nickname: Robot nickname, used to find the device
Returns:
{
"code": 0,
"msg": "success",
"data": {
"ctl": {
"data": {
"ret": "ok",
"cleanSt": "h",
"chargeSt": "charging",
"stationSt": "i"
}
}
}
}
Status Code Description:
| Parameter | Type | Description |
|---|---|---|
| cleanSt | string | Cleaning status, exists when request is successful. s-cleaning, p-paused, h-idle, goposition-going to specified position, gopositionpause-stopped at specified point, findpet-finding pet, findpetpause-pet finding paused, cruise-cruising, cruisepause-cruise paused, buildmap-creating map, buildmappause-map building paused |
| chargeSt | string | Charging status, exists when request is successful. g-returning to charge, gp-return to charge paused, i-idle, sc-dock charging, wc-wire charging, charging-charging (includes SC and WC) |
| stationSt | string | Station status, i-idle, wash-washing mop, dry-drying, drypause-drying paused, dust-dust collecting, dustpause-dust collection paused, clean-station cleaning, cleanpause-station cleaning paused, wash-washing mop, washpause-mop washing paused |
Getting Started
Installation
GitHub Local Installation
git clone git@github.com:ecovacs-ai/ecovacs-mcp.git
uv add "mcp[cli]" mcp requests
uv run ecovacs_mcp/robot_mcp_stdio.py
pipy
pip install ecovacs-robot-mcp
python3 -m ecovacs_robot_mcp
Environment Variables
ECO_API_KEY: API access key, used to authenticate API call permissionsECO_API_URL: API HOST- Mainland China:
https://open.ecovacs.cn - Outside Mainland China:
https://open.ecovacs.com
- Mainland China:
Get AK & Delete AK
Before choosing between the two methods (local or SSE), you need to create a server AK in the Ecovacs Open Platform Console to call the robot's API capabilities through the AK.
If you want to cancel the authorization, you can also remove the AK authorization in the Ecovacs Open Platform Console.
Ecovacs Open Platform (Mainland China): https://open.ecovacs.cn
Ecovacs Open Platform (Outside Mainland China): https://open.ecovacs.com
Server Config
{
"mcpServers": {
"ecovacs_mcp": {
"command": "/Users/home/.local/bin/uv",
"args": [
"--directory",
"/Users/home/ecovacs-mcp-main/ecovacs_mcp",
"run",
"robot_mcp_stdio.py"
],
"env": {
"ECO_API_KEY": "your AK...........",
"ECO_API_URL": "https://open.ecovacs.com"
}
}
}
}