Ecovacs Robot Control

Controla y consulta el estado de los robots de limpieza Ecovacs utilizando el protocolo MCP.

Documentación

Servidor MCP de Control de Robot Aspirador

English | Español

La API principal de Ecovacs ahora es totalmente compatible con el protocolo MCP, siendo el primer proveedor de robots compatible con MCP a nivel mundial.

Ecovacs ha completado la integración de 4 interfaces API principales con el protocolo MCP, incluyendo consulta de lista de dispositivos, control de limpieza, control de retorno a la base y consulta de estado de trabajo.

Como el primer proveedor de robots de limpieza compatible con MCP a nivel mundial, tras el lanzamiento del Servidor MCP de Ecovacs, los desarrolladores de agentes inteligentes solo necesitan una configuración simple para integrar rápidamente los servicios de robots en modelos grandes, logrando capacidades como consulta, limpieza y retorno a la base.

Esto reduce significativamente la barrera para invocar las capacidades relacionadas con el control de robots en el desarrollo de aplicaciones de agentes inteligentes, mejorando notablemente la eficiencia de desarrollo de dichas aplicaciones.

Herramientas

Consulta de lista de dispositivos

Obtiene la lista de todos los robots vinculados al usuario.

Entrada:

Sin parámetros

Retorno:

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

Iniciar limpieza

Controla el inicio, pausa, reanudación o detención de la limpieza del robot aspirador.

Entrada:

nickname: Apodo del robot, utilizado para buscar el dispositivo, admite coincidencia difusa
act: Comportamiento de limpieza
- s: Iniciar limpieza
- r: Reanudar limpieza
- p: Pausar limpieza
- h: Detener limpieza

Retorno:

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

Controlar retorno a la base

Controla el inicio o detención del retorno a la base del robot.

Entrada:

nickname: Apodo del robot, utilizado para buscar el dispositivo
act: Comportamiento del robot
- go-start: Iniciar retorno a la base
- stopGo: Finalizar retorno a la base

Retorno:

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

Consultar estado de trabajo

Consulta el estado de trabajo actual del robot.

Entrada:

nickname: Apodo del robot, utilizado para buscar el dispositivo

Retorno:

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

Descripción de códigos de estado:

Parámetro	Tipo	Descripción
cleanSt	string	Estado de limpieza, presente cuando la solicitud es exitosa. s- limpiando, p- pausado, h- inactivo, goposition- yendo a la posición especificada, gopositionpause- detenido en el punto especificado, findpet- buscando mascota, findpetpause- búsqueda de mascota en pausa, cruise- en crucero, cruisepause- crucero en pausa, buildmap- creando mapa, buildmappause- creación de mapa en pausa
chargeSt	string	Estado de carga, presente cuando la solicitud es exitosa. g- cargando de regreso, gp- pausa de carga de regreso, i- inactivo, sc- carga en base, wc- carga por cable, charging- cargando (incluye SC y WC)
stationSt	string	Estado de la estación base, i- inactivo, wash- limpiando el trapo, dry- secando, drypause- secado en pausa, dust- recogiendo polvo, dustpause- recogida de polvo en pausa, clean- limpieza de la estación base, cleanpause- limpieza de la estación base en pausa, wash- limpiando el trapo, washpause- limpieza del trapo en pausa

Comenzar

Instalación

Instalación local desde 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

Variables de entorno

ECO_API_KEY: Clave de acceso a la API, utilizada para verificar los permisos de invocación de la interfaz
ECO_API_URL: HOST de la API
- China continental: https://open.ecovacs.cn
- Fuera de China continental: https://open.ecovacs.com

Obtener AK y eliminar AK

Antes de elegir entre los dos métodos (local o SSE), debes crear un AK de servidor en la consola de la plataforma abierta de Ecovacs. Solo a través del AK podrás invocar las capacidades de la API del robot.

Si deseas cancelar la autorización, también puedes eliminar la autorización del AK en la consola de la plataforma abierta de Ecovacs.

Plataforma abierta de Ecovacs (China continental): https://open.ecovacs.cn

Plataforma abierta de Ecovacs (fuera de China continental): https://open.ecovacs.com

Configuración

Agrega la siguiente configuración en cualquier cliente MCP (como Claude.app). En algunos clientes puede ser necesario realizar algunos ajustes de formato.

Donde ECO_API_KEY es la clave de acceso a la API ECO_API_URL es el HOST de la API

Usando 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
      }
    }
  }
}

Usando instalación con pip

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

Ejemplo de uso (Claude)

Abre la Configuración de Claude for Desktop, cambia a Desarrollador, haz clic en Editar Config y abre el archivo de configuración con cualquier IDE.

Agrega la siguiente configuración al archivo de configuración. ECO_API_KEY es el AK para acceder a la API de la plataforma abierta de Ecovacs, que se solicita en esta página:

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

Reinicia Claude. En este momento, el panel de configuración ya ha cargado correctamente el Servidor MCP del robot Ecovacs. En el cuadro de diálogo de la interfaz principal del software se pueden ver 4 herramientas MCP disponibles; haz clic para ver los detalles.

Efecto

A continuación, puedes hacer preguntas para verificar las capacidades del asistente del robot Ecovacs.

Ejemplo de uso (Cursor)

Entrar en la interfaz de configuración de Cursor para configurar la conexión SSE

Agregar una nueva configuración de Servidor MCP

China continental

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

Fuera de China continental

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

Volver a la interfaz de configuración de Cursor para ver el estado de las herramientas del servicio MCP

Seleccionar el modelo grande de Cursor para tener una mejor experiencia de servicio; se recomienda elegir claude-3.7-sonnet

Modo de interacción del modelo: elegir el modo Agente

Efecto

Licencia

MIT © ecovacs

Comentarios

Si encuentras cualquier problema al usar el Servidor MCP del robot Ecovacs, no dudes en enviar un issue或者联系我们，我们也欢迎每一个积极的PR`. Agradecemos mucho tu apoyo y contribución ❤️

Contacto

Correo: pei.zhou@ecovacs.com

Wechat:

Actualizaciones

Versión	Descripción de funciones	Fecha de actualización
V1.0	Lanzamiento oficial del Servidor MCP de Ecovacs	24 de abril de 2025