Skip to main content
Glama
ecovacs-ai

Ecovacs MCP Server

Official
by ecovacs-ai
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

扫地机器人控制MCP Server

English | 中文

科沃斯核心API现已全面兼容MCP协议，是全球首家兼容MCP协议的机器人服务商。

科沃斯已经完成了4个核心API接口和MCP协议的对接，包括设备列表查询、清扫控制、回充控制和工作状态查询。

作为全球首家支持MCP协议的清洁机器人服务商，科沃斯MCP Server发布后，智能体开发者仅需简单配置，就可以在大模型中快速接入机器人服务，实现查询、清扫、回充等能力。

大幅降低了智能体应用开发过程中调用机器人控制服务相关能力的门槛，显著提升了智能体应用的开发效率。

工具

设备列表查询

获取用户绑定的所有机器人列表。

Input:

无参数

Returns:

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

启动清扫

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

Input:

  • nickname: 机器人的昵称，用于查找设备，支持模糊匹配

  • act: 清扫行为

    • s: 开始清扫

    • r: 恢复清扫

    • p: 暂停清扫

    • h: 停止清扫

Returns:

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

控制回充

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

Input:

  • nickname: 机器人昵称，用于查找设备

  • act: 机器行为

    • go-start: 开始回充

    • stopGo: 结束回充

Returns:

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

查询工作状态

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

Input:

  • nickname: 机器人昵称，用于查找设备

Returns:

{
	"code": 0,
	"msg": "success",
	"data": {
		"ctl": {
			"data": {
				"ret": "ok",
				"cleanSt": "h",
				"chargeSt": "charging",
				"stationSt": "i"
			}
		}
	}
}

状态码说明：

参数名

类型

说明

cleanSt

string

清扫状态，请求成功时存在。s-清扫中，p-暂停中，h-空闲中，goposition-正在前往指定位置，gopositionpause-在指定点停止，findpet-寻找宠物，findpetpause-寻找宠物暂停，cruise-巡航中，cruisepause-巡航暂停，buildmap-创建地图，buildmappause-建图暂停

chargeSt

string

充电状态，请求成功时存在。g-正在回充，gp-回充暂停，i-空闲，sc-底座充电，wc-线充，charging-充电中（包括SC和WC）

stationSt

string

基站状态，i-空闲，wash-正在清洗拖布，dry-正在烘干，drypause-烘干暂停，dust-集尘中，dustpause-集尘暂停，clean-基站清洁，cleanpause-基站清洁暂停，wash-清洗拖布，washpause-清洗拖布暂停

Related MCP server: matter-controller-mcp

开始

安装

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

pipy

pip install ecovacs-robot-mcp

python3 -m ecovacs_robot_mcp

环境变量

  • ECO_API_KEY: API访问密钥，用于验证接口调用权限

  • ECO_API_URL: API HOST

    • 中国内地： https://open.ecovacs.cn

    • 非中国内地： https://open.ecovacs.com

获取AK & 删除AK

在选择两种方法（本地或者SSE）之前，你需要在科沃斯开放平台的控制台中创建一个服务端AK，通过AK你才能够调用机器人的API能力。

如果你想取消授权，在科沃斯开放平台的控制台中同样可以移除AK的授权。

科沃斯开放平台（中国内地）：https://open.ecovacs.cn

科沃斯开放平台（非中国内地）：https://open.ecovacs.com

配置

在任意MCP客户端（如Claude.app）中添加如下配置，部分客户端下可能需要做一些格式化调整。

其中 ECO_API_KEY为API访问密钥 ECO_API_URL为API HOST

  • Using uvx

{
  "mcpServers": {
    "ecovacs_mcp": {
      "command": "uvx",
      "args": ["ecovacs-robot-mcp"],
      "env": {
        "ECO_API_KEY": "your AK...........",
        "ECO_API_URL": "https://open.ecovacs.cn" // 如果是非中国内地，配置为 https://open.ecovacs.com
      }
    }
  }
}

  • Using pip installation

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

使用示例（Claude示列）

打开Claude for Desktop的Setting，切换到Developer，点击Edit Config，用任意的IDE打开配置文件。

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

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

重启Claude，此时设置面板已经成功加载了科沃斯机器人MCP Server。在软件主界面对话框处可以看到有4个可用的MCP工具，点击可以查看详情。

效果

接下来就可以进行提问，验证科沃斯机器人小助手的能力了。

使用示例（Cursor示列）

进入 Cursor 设置界面配置 SSE 连接

添加一个新的 MCP Server 配置

  • 中国内地

{
  "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
    }
  }
}

  • 非中国内地

{
  "mcpServers": {
    "robot_control_server": {
      "url": "https://mcp-open.ecovacs.com/sse?ak=your ak"
    }
  }
}

返回 Cursor 设置界面查看 MCP 服务工具状态

选择配置 Cursor 大模型让你拥有更好的服务体验，建议选择 claude-3.7-sonnet

模型交互模式 ：选择 Agent 方式

效果

许可证

MIT © ecovacs

反馈

在使用科沃斯机器人MCP Server时遇到的任何问题，欢迎通过issue或者联系我们，我们也欢迎每一个积极的PR`，非常感谢各位的支持与贡献❤️

联系方式

Mail： pei.zhou@ecovacs.com

Wechat：

更新

版本

功能说明

更新日期

V1.0

Ecovacs MCP Server正式上线

2025年4月24日

Available Tools

4 tools
get_device_listC

Query robot list

Returns: Dict: Dictionary containing list of robot nicknames

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It states the tool returns a dictionary of robot nicknames, which implies a read-only operation, but doesn't disclose behavioral traits like authentication needs, rate limits, error handling, or whether it's a safe operation. The description is minimal and lacks crucial context for an agent to understand how it behaves beyond basic output.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise with two short sentences: 'Query robot list' and 'Returns: Dict: Dictionary containing list of robot nicknames'. It's front-loaded with the purpose and efficiently states the return type. However, it could be slightly more structured by clarifying the tool's role relative to siblings, but it earns high marks for brevity and lack of waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 0 parameters, no annotations, and no output schema, the description provides minimal but adequate context for a simple query tool. It states what the tool does and the return format, but lacks details on behavioral aspects like safety or usage guidelines. For a tool with no structured data, it meets the minimum viable threshold but has clear gaps in completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description doesn't add parameter info, which is appropriate here. Baseline is 4 for zero parameters, as the schema fully covers the absence of inputs, and the description doesn't need to compensate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Query robot list' which indicates the tool retrieves robot information, but it's vague about what specific data is returned beyond 'list of robot nicknames'. It doesn't distinguish from sibling tools like get_work_state, set_charging, or set_cleaning, which have different purposes. The description provides a basic purpose but lacks specificity about scope or differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives. The description doesn't mention prerequisites, context, or exclusions. It fails to explain how this tool relates to siblings like get_work_state (which might provide status info) or set_charging/set_cleaning (which are mutation tools). No explicit or implied usage scenarios are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_work_stateC

Query robot working status

Args: nickname: Robot nickname, used to find device

Returns: Dict: Dictionary containing robot working status

ParametersJSON Schema
NameRequiredDescriptionDefault
nicknameYesRobot nickname, used to find device

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a query operation but doesn't mention whether it's read-only, requires authentication, has rate limits, or what specific status information is returned. The description provides minimal behavioral context beyond the basic operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is reasonably concise with clear sections for Args and Returns, but the 'Query robot working status' statement is somewhat vague. The structure is functional but not optimally front-loaded with the most critical information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a query tool with no annotations and no output schema, the description is insufficient. It doesn't explain what specific status information is returned, what format the dictionary contains, or any error conditions. Given the complexity of querying device status, more context is needed for effective tool use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already fully documents the single 'nickname' parameter. The description repeats the parameter documentation verbatim without adding any additional meaning or context beyond what's in the schema, meeting the baseline expectation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Query' and resource 'robot working status', making the purpose understandable. However, it doesn't differentiate from sibling tools like 'get_device_list' which might also provide status information, preventing a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like 'get_device_list' or when not to use it. The description lacks any context about prerequisites or appropriate scenarios for querying robot status.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_chargingB

Make robot return to charging station

Args: nickname: Robot nickname, used to find device act: Robot action, go-start begin returning to charging station, stopGo stop returning to charging station

Returns: Dict: Dictionary containing execution results

ParametersJSON Schema
NameRequiredDescriptionDefault
nicknameYesRobot nickname, used to find device
actNoRobot action, go-start begin returning to charging station, stopGo stop returning to charging stationgo-start

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the robot action types but doesn't cover important aspects like whether this requires specific permissions, what happens if the robot is already charging, whether the action is reversible, or potential error conditions. The return value description ('Dictionary containing execution results') is too vague.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately brief with a clear purpose statement followed by structured Args and Returns sections. However, the parameter descriptions in the Args section are redundant with the schema and could be more concise. The overall structure is logical and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what the execution results dictionary contains, what success/failure looks like, or important behavioral constraints. Given the complexity of controlling physical robot behavior, more context about limitations, safety considerations, or state dependencies would be needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters completely. The description repeats the parameter information verbatim without adding any additional context, syntax examples, or format details beyond what the schema provides. This meets the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Make robot return to charging station') and identifies the resource (robot). It distinguishes from sibling tools like 'set_cleaning' by focusing on charging behavior rather than cleaning. However, it doesn't explicitly contrast with 'get_device_list' or 'get_work_state' which are read-only operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage through the parameter descriptions ('go-start begin returning', 'stopGo stop returning'), suggesting when to use different actions. However, it doesn't provide explicit guidance on when to choose this tool over alternatives like 'set_cleaning' or mention prerequisites such as robot availability.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_cleaningC

Start robot cleaning

Args: nickname: Robot nickname, used to find device act: Cleaning action s-start cleaning, r-resume cleaning, p-pause cleaning, h-stop cleaning Returns: Dict: Dictionary containing execution results

ParametersJSON Schema
NameRequiredDescriptionDefault
nicknameNoRobot nickname, supports fuzzy matching
actNoCleaning action, s-start cleaning, r-resume cleaning, p-pause cleaning, h-stop cleanings

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the action types (start, resume, pause, stop) but lacks critical details such as required permissions, error conditions, or side effects (e.g., whether the robot moves immediately). This is insufficient for a mutation tool with zero annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded with the main purpose. The structured 'Args' and 'Returns' sections are clear, though the formatting could be slightly more polished (e.g., using bullet points). Overall, it's efficient with little waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of controlling a robot (a mutation tool with no annotations and no output schema), the description is incomplete. It lacks information on return values (only states 'Dict' without details), error handling, and how it integrates with sibling tools, leaving significant gaps for the agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters fully. The description adds minimal value by restating the 'act' parameter's options in a slightly different format but doesn't provide additional context like examples or edge cases beyond what the schema specifies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Start robot cleaning') and resource (robot), making the purpose understandable. However, it doesn't explicitly differentiate from sibling tools like 'set_charging' or 'get_work_state', which would require a more specific comparison to achieve a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. For example, it doesn't mention prerequisites like needing a robot device from 'get_device_list' or how it relates to checking status with 'get_work_state'. This leaves the agent without context for tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 4 tool updates
    • First observedget_device_list
    • First observedget_work_state
    • First observedset_charging
    • First observedset_cleaning
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.3/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: get_device_list retrieves robot information, get_work_state queries status, set_charging controls charging behavior, and set_cleaning manages cleaning operations. There is no overlap or ambiguity between these functions.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern with clear, descriptive names: get_device_list, get_work_state, set_charging, and set_cleaning. The naming convention is uniform throughout the set.

Tool Count4/5

With 4 tools, the count is reasonable for a robot vacuum control server, covering core operations like listing devices, checking status, and controlling charging and cleaning. It is slightly thin but functional for basic control.

Completeness3/5

The tools cover essential operations for robot vacuum control, but there are notable gaps such as missing update/delete functions for device management, scheduling capabilities, or advanced settings like cleaning modes. The surface is functional but not fully comprehensive.

Maintenance

ActivityInactive
ResponsivenessUnresponsive

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Eufy RoboVac MCP Server

    appleton
    A
    license
    B
    quality
    D
    maintenance
    A Model Context Protocol server for controlling Eufy RoboVac vacuum cleaners, enabling users to scan for devices, connect to them, and execute various cleaning commands through natural language.
    20
    1,783
    1
    MIT

  • matter-controller-mcp

    0x1abin
    A
    license
    Not graded
    quality
    D
    maintenance
    A powerful MCP server that enables AI assistants to discover, commission, and control Matter-compatible smart home devices through a standardized interface.
    21
    8
    MIT

  • ha-mcp

    osrd-gh
    A
    license
    Not graded
    quality
    C
    maintenance
    An MCP server that enables AI assistants to control Home Assistant via natural language, including device control, automation management, and system configuration.
    MIT

  • Hermejia

    HuishanLi1997
    A
    license
    Not graded
    quality
    C
    maintenance
    MCP server that enables AI agents to control Xiaomi Mi Home smart devices through natural language, with support for listing devices, controlling properties, and running scenes.
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ecovacs-ai/ecovacs-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server