home / mcp / ecovacs mcp server

Ecovacs MCP Server

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "ecovacs-ai-ecovacs-mcp": {
      "url": "https://mcp-open.ecovacs.cn/sse?ak=your ak",
      "headers": {
        "ECO_API_KEY": "your AK...........",
        "ECO_API_URL": "https://open.ecovacs.cn"
      }
    }
  }
}

Ecovacs MCP Server exposes the Ecovacs robot controls through the MCP protocol, enabling you to query your devices, start and manage cleaning, control charging, and monitor current work status from compatible MCP clients. This server bridges your ecosystem with Ecovacs robots, reducing integration effort and accelerating development of robot-enabled experiences.

How to use

You connect with an MCP client to access four core capabilities: list your bound devices, start or pause cleaning, initiate or stop automatic charging, and query the robot’s current state. Use the HTTP (sse) endpoint or local STDIO servers described below to reach the Ecovacs MCP Server from your agent or application. Once connected, you can request device lists, issue cleaning commands, toggle charging, and read live status data like cleaning state and battery/charging information.

How to install

Prerequisites: you need a runtime for your chosen MCP client. This guide covers both remote HTTP access and local STDIO configurations.

1) Set up API access: obtain an API key (AK) from the Ecovacs Open Platform console and note the API URL for your region.

2) Choose your MCP connection mode. You can use a remote HTTP endpoint or run a local MCP server process and connect via STDIO.

3) Configure the MCP client with the appropriate server entry from the configurations below.

Configuration

HTTP (remote) configuration (preferred if you want a single central server): you connect to the MCP SSE endpoint using your AK. Mainland China endpoints and non-China endpoints differ, so pick the one that matches your region.

{
  "mcpServers": {
    "robot_control_server": {
      "type": "http",
      "name": "robot_control_server_http",
      "url": "https://mcp-open.ecovacs.cn/sse?ak=your ak"
    }
  }
}

STDIO (local) configuration

If you prefer to run the MCP server locally and connect via STDIO, use one of the following configurations. You can run these in your MCP client’s config panel or environment setup.

{
  "mcpServers": {
    "ecovacs_mcp": {
      "command": "uvx",
      "args": ["ecovacs-robot-mcp"],
      "env": {
        "ECO_API_KEY": "your AK...........",
        "ECO_API_URL": "https://open.ecovacs.cn" 
      }
    }
  }
}

Additional notes

Environment variables ECO_API_KEY and ECO_API_URL are required to authorize and route API calls. If you are outside Mainland China, use the corresponding non‑China API URL.

Security and access control

Keep your API key confidential. Rotate keys if a leak is suspected. Only expose the MCP server to trusted clients and restrict network access to necessary routes.

Troubleshooting

If you cannot reach the MCP endpoint, verify your AK, API URL, and region. Check that the server process is running (for STDIO) and that the MCP client is configured with the correct command, arguments, and environment variables.

Available tools

list_devices

Query all robots bound to the user and return a list of devices with nicknames.

start_clean

Start, pause, resume, or stop cleaning on a specified robot using its nickname.

control_charge

Command the robot to begin or stop returning to its charging dock.

query_status

Retrieve the current work status of a specified robot, including cleaning and charging states.