Content
# Tool List
[English](README_EN.md) |
Ecovacs core API is now fully compatible with the MCP protocol, making it the first robot service provider globally to support this protocol.
Ecovacs has successfully integrated four core API interfaces with the MCP protocol, including device list query, sweep control, return-to-charge control, and work status query.
As the first cleaning robot service provider to support the MCP protocol, the release of Ecovacs MCP Server enables developers to easily integrate robot services into their large models with simple configuration, allowing for capabilities such as query, sweep, and return-to-charge.
This significantly reduces the threshold for invoking robot control service capabilities during intelligent application development and notably enhances development efficiency.
## Tools
### Device List Query
Get a list of all robots bound to the user.
#### Input:
No parameters
#### Returns:
```json
{
"status": 0,
"message": "success",
"data": [
{
"nickname": "Robot Nickname",
}
]
}
```
### Start Sweeping
Control the sweeping robot to start, pause, resume, or stop sweeping.
#### Input:
- `nickname`: The robot's nickname, used to find the device, supporting fuzzy matching
- `act`: Sweeping action
- `s`: Start sweeping
- `r`: Resume sweeping
- `p`: Pause sweeping
- `h`: Stop sweeping
#### Returns:
```json
{
"msg": "OK",
"code": 0,
"data": []
}
```
### Control Return-to-Charge
Control the robot to start or stop returning to charge.
#### Input:
- `nickname`: Robot nickname, used to find the device
- `act`: Robot action
- `go-start`: Start returning to charge
- `stopGo`: Stop returning to charge
#### Returns:
```json
{
"msg": "OK",
"code": 0,
"data": []
}
```
### Query Work Status
Query the current work status of the robot.
#### Input:
- `nickname`: Robot nickname, used to find the device
#### Returns:
```json
{
"code": 0,
"msg": "success",
"data": {
"ctl": {
"data": {
"ret": "ok",
"cleanSt": "h",
"chargeSt": "charging",
"stationSt": "i"
}
}
}
}
```
**Status Code Description:**
| Parameter Name | Type | Description |
| -------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| cleanSt | string | Sweeping status, exists when the request is successful. s-sweeping, p-paused, h-idle, goposition-moving to a specified position, gopositionpause-stopped at a specified point, findpet-seeking pet, findpetpause-seeking pet paused, cruise-cruising, cruisepause-cruising paused, buildmap-creating a map, buildmappause-map creation paused |
| chargeSt | string | Charging status, exists when the request is successful. g-returning to charge, gp-returning to charge paused, i-idle, sc-base station charging, wc-wire charging, charging-charging (including SC and WC) |
| stationSt | string | Base station status, i-idle, wash-washing the mop, dry-drying, drypause-drying paused, dust-collecting dust, dustpause-collecting dust paused, clean-base station cleaning, cleanpause-base station cleaning paused, wash-washing the mop, washpause-washing the mop paused |
## Getting Started
## Installation
### Local Installation via GitHub
```bash
git clone git@github.com:ecovacs-ai/ecovacs-mcp.git
uv add "mcp[cli]" mcp requests
uv run ecovacs_mcp/robot_mcp_stdio.py
```
### Installation via PyPI
```
pip install ecovacs-robot-mcp
python3 -m ecovacs_robot_mcp
```
## Environment Variables
- `ECO_API_KEY`: API access key, used to verify interface call permissions
- `ECO_API_URL`: API host
- Mainland China: `https://open.ecovacs.cn`
- Non-Mainland China: `https://open.ecovacs.com`
## Obtain and Delete AK
Before choosing between the two methods (local or SSE), you need to create a server-side AK on the [Ecovacs Open Platform Console](https://open.ecovacs.cn). With this AK, you can call the robot's API capabilities.
If you want to cancel authorization, you can also remove the AK's authorization on the [Ecovacs Open Platform Console](https://open.ecovacs.cn).
Ecovacs Open Platform (Mainland China): https://open.ecovacs.cn
Ecovacs Open Platform (Non-Mainland China): https://open.ecovacs.com
<img src="images/img_v3_02lo_b450632b-9dbe-4cd9-aead-c625ad3458fg.jpg" alt="Get AK" width="600" />
## Configuration
Add the following configuration to any MCP client (such as Claude.app), and some clients may require formatting adjustments.
Where `ECO_API_KEY` is the API access key and `ECO_API_URL` is the API host.
- Using uvx
```json
{
"mcpServers": {
"ecovacs_mcp": {
"command": "uvx",
"args": ["ecovacs-robot-mcp"],
"env": {
"ECO_API_KEY": "your AK...........",
"ECO_API_URL": "https://open.ecovacs.cn" // For regions outside Mainland China, configure as https://open.ecovacs.com
}
}
}
}
```
- Using pip installation
```json
{
"mcpServers": {
"ecovacs_mcp": {
"command": "python",
"args": ["-m", "ecovacs_robot_mcp"],
"env": {
"ECO_API_KEY": "your AK...........",
"ECO_API_URL": "https://open.ecovacs.cn" // For regions outside Mainland China, configure as https://open.ecovacs.com
}
}
}
}
```
## Usage Example (Claude)
Open Claude for Desktop's Setting, switch to Developer, click Edit Config, and use any IDE to open the configuration file.
<img src="images/img_v3_02lm_ac10ff15-8764-4ad3-906c-5c8433a9e5eg.jpg" alt="Claude Settings Interface" width="600" />
<img src="images/img_v3_02lm_2ced9293-af22-4d9f-a70c-337643a93c7g.jpg" alt="Claude Configuration File" width="600" />
Add the following configuration to the configuration file. `ECO_API_KEY` is the AK for accessing the Ecovacs Open Platform API, which can be applied for on [this page](https://open.ecovacs.cn/preparationForUse).
```json
{
"mcpServers": {
"ecovacs_mcp": {
"command": "python3",
"args": ["-m", "ecovacs_robot_mcp"],
"env": {
"ECO_API_KEY": "your ak......",
"ECO_API_URL": "https://open.ecovacs.cn"// For regions outside Mainland China, configure as https://open.ecovacs.com
}
}
}
}
```
Restart Claude. The Ecovacs robot MCP Server has been successfully loaded on the settings panel. On the main interface dialog box, you can see four available MCP tools. Click to view details.
<img src="images/img_v3_02lm_e1b700d6-9693-4448-8acf-d622f28b3b3g.jpg" alt="Claude MCP Tools" width="600" />
#### Effect
You can now ask questions and verify the capabilities of the Ecovacs robot assistant.
<img src="images/img_v3_02lm_2f3b431a-c289-4476-8a24-1ff1a231aadg.jpg" alt="Claude Interaction Effect" width="600" />
## Usage Example (Cursor)
### Enter Cursor Settings Interface to Configure SSE Connection
<img src="images/doc_1743660020811_d2b5c.6bec4f04.png" alt="Cursor Settings Interface" width="600" />
### Add a New MCP Server Configuration
- Mainland China
```json
{
"mcpServers": {
"robot_control_server": {
"url": "https://mcp-open.ecovacs.cn/sse?ak=your ak"
// For regions outside Mainland China, configure as https://mcp-open.ecovacs.com/sse?ak=your ak
}
}
}
```
- Non-Mainland China
```json
{
"mcpServers": {
"robot_control_server": {
"url": "https://mcp-open.ecovacs.com/sse?ak=your ak"
}
}
}
```
### Return to Cursor Settings Interface to View MCP Service Tool Status
<img src="images/20250423-175131.0caa52fa.jpg" alt="Cursor MCP Service Status" width="600" />
### Select Configuration Cursor Large Model for Better Service Experience, Recommended to Choose claude-3.7-sonnet
<img src="images/doc_1743660126834_d2b5c.fc9da8f3.png" alt="Cursor Model Configuration" width="600" />
### Model Interaction Mode: Choose Agent Mode
<img src="images/doc_1743660181250_d2b5c.1d9a47eb.png" alt="Cursor Interaction Mode" width="600" />
### Effect
<img src="images/img_v3_02lm_f5094f2f-7cf3-4ee4-a5f9-ae29b746175g.jpg" alt="Cursor Interaction Mode" width="600" />
## License
[MIT](LICENSE) © ecovacs
## Feedback
If you encounter any issues while using Ecovacs Robot MCP Server, please feel free to report them through `issue` or contact us. We also welcome any positive `PR`, and we greatly appreciate your support and contributions ❤️
## Contact Us
Mail: pei.zhou@ecovacs.com
Wechat:
<img src="images/img_v3_02lm_d2a67ba9-6fa2-4f96-9d37-09f8d8b8e21g.png" alt="WeChat QR Code" width="200" />
## Update
| Version | Feature Description | Update Date | | | |
| ---- | -------------------------- | ------------- | ---- | ---- | ---- |
| V1.0 | Ecovacs MCP Server officially launched | April 24, 2025 | | | |
