Ecovacs Robot Control

Controle e consulte o status de robôs de limpeza Ecovacs usando o protocolo MCP.

Documentação

MCP Server de Controle de Robô Aspirador

English | Português

A API principal da Ecovacs agora é totalmente compatível com o protocolo MCP, sendo o primeiro fornecedor de robôs do mundo compatível com o protocolo MCP.

A Ecovacs já concluiu a integração de 4 interfaces de API principais com o protocolo MCP, incluindo consulta de lista de dispositivos, controle de limpeza, controle de retorno à base e consulta de status de trabalho.

Como o primeiro fornecedor de robôs de limpeza do mundo a suportar o protocolo MCP, após o lançamento do Ecovacs Robot Control MCP Server, os desenvolvedores de agentes inteligentes podem, com uma configuração simples, integrar rapidamente os serviços de robô em grandes modelos, implementando capacidades como consulta, limpeza e retorno à base.

Isso reduz significativamente a barreira para chamar capacidades relacionadas ao serviço de controle de robôs durante o desenvolvimento de aplicações de agentes inteligentes, aumentando notavelmente a eficiência do desenvolvimento de aplicações de agentes inteligentes.

Ferramentas

Consulta de Lista de Dispositivos

Obtém a lista de todos os robôs vinculados ao usuário.

Entrada:

Sem parâmetros

Retorna:

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

Iniciar Limpeza

Controla o robô aspirador para iniciar, pausar, retomar ou parar a limpeza.

Entrada:

nickname: O apelido do robô, usado para localizar o dispositivo, suporta correspondência difusa.
act: Comportamento de limpeza
- s: Iniciar limpeza
- r: Retomar limpeza
- p: Pausar limpeza
- h: Parar limpeza

Retorna:

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

Controlar Retorno à Base

Controla o robô para iniciar ou parar o retorno à base.

Entrada:

nickname: Apelido do robô, usado para localizar o dispositivo
act: Comportamento do robô
- go-start: Iniciar retorno à base
- stopGo: Encerrar retorno à base

Retorna:

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

Consultar Status de Trabalho

Consulta o status de trabalho atual do robô.

Entrada:

nickname: Apelido do robô, usado para localizar o dispositivo

Retorna:

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

Explicação dos códigos de status:

Nome do parâmetro	Tipo	Descrição
cleanSt	string	Status de limpeza, presente quando a solicitação é bem-sucedida. s- limpando, p- pausado, h- ocioso, goposition- indo para a posição especificada, gopositionpause- parado no ponto especificado, findpet- procurando animal de estimação, findpetpause- pausa na procura de animal de estimação, cruise- em cruzeiro, cruisepause- pausa no cruzeiro, buildmap- criando mapa, buildmappause- pausa na criação de mapa
chargeSt	string	Status de carregamento, presente quando a solicitação é bem-sucedida. g- retornando à base, gp- pausa no retorno, i- ocioso, sc- carregando na base, wc- carregando com fio, charging- carregando (incluindo SC e WC)
stationSt	string	Status da estação base, i- ocioso, wash- lavando o pano de limpeza, dry- secando, drypause- pausa na secagem, dust- coletando poeira, dustpause- pausa na coleta de poeira, clean- limpeza da estação base, cleanpause- pausa na limpeza da estação base, wash- lavando o pano de limpeza, washpause- pausa na lavagem do pano de limpeza

Início

Instalação

Instalação local via 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

Variáveis de Ambiente

ECO_API_KEY: Chave de acesso da API, usada para verificar a permissão de chamada da interface
ECO_API_URL: API HOST
- China continental: https://open.ecovacs.cn
- Fora da China continental: https://open.ecovacs.com

Obter AK & Excluir AK

Antes de escolher entre os dois métodos (local ou SSE), você precisa criar um AK de servidor no console da plataforma aberta da Ecovacs. Através do AK, você poderá chamar as capacidades da API do robô.

Se você quiser cancelar a autorização, também pode remover a autorização do AK no console da plataforma aberta da Ecovacs.

Plataforma aberta da Ecovacs (China continental): https://open.ecovacs.cn

Plataforma aberta da Ecovacs (fora da China continental): https://open.ecovacs.com

Configuração

Adicione a seguinte configuração em qualquer cliente MCP (como Claude.app). Em alguns clientes, pode ser necessário fazer alguns ajustes de formatação.

Onde ECO_API_KEY é a chave de acesso da API ECO_API_URL é o API HOST

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 instalação via 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
      }
    }
  }
}

Exemplo de Uso (Exemplo com Claude)

Abra as Configurações do Claude for Desktop, mude para Desenvolvedor, clique em Editar Config e abra o arquivo de configuração com qualquer IDE.

Adicione a seguinte configuração ao arquivo de configuração. ECO_API_KEY é o AK para acessar a API da plataforma aberta da Ecovacs, solicite-o nesta 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
            }
        }
    }
}

Reinicie o Claude. Neste momento, o painel de configurações já carregou com sucesso o Ecovacs Robot Control MCP Server. Na caixa de diálogo da interface principal do software, você pode ver 4 ferramentas MCP disponíveis. Clique para ver os detalhes.

Efeito

Agora você pode fazer perguntas para verificar as capacidades do assistente de robô da Ecovacs.

Exemplo de Uso (Exemplo com Cursor)

Entre na interface de configurações do Cursor para configurar a conexão SSE

Adicione uma nova configuração de MCP Server

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

Fora da China continental

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

Volte à interface de configurações do Cursor para ver o status das ferramentas do serviço MCP

Selecione o modelo grande do Cursor para ter uma melhor experiência de serviço. Recomenda-se escolher claude-3.7-sonnet

Modo de interação do modelo: selecione o modo Agente

Efeito

Licença

MIT © ecovacs

Feedback

Para qualquer problema encontrado ao usar o Ecovacs Robot Control MCP Server, sinta-se à vontade para enviar um PR através de issue或者联系我们，我们也欢迎每一个积极的. Muito obrigado pelo seu apoio e contribuição ❤️

Contato

E-mail: pei.zhou@ecovacs.com

Wechat:

Atualizações

Versão	Descrição da funcionalidade	Data de atualização
V1.0	Lançamento oficial do Ecovacs Robot Control MCP Server	24 de abril de 2025