OPenSprinkler MCP Server

OpenSprinkler MCP Server

Servidor MCP para gerenciar o controlador OpenSprinkler via Claude Desktop ou qualquer cliente compatível com MCP.

Restrição: Apenas um controlador pode ser gerenciado por vez. Isso pode ser alterado no futuro se necessário, mas por enquanto é uma limitação do design.

Ferramentas Disponíveis

Ferramenta	Descrição
get_controller_status	Obter status do controlador (hora do dispositivo, estado de habilitação, atraso de chuva)
get_stations	Obter todas as estações com seu status atual
run_station	Iniciar uma estação por uma duração especificada
stop_station	Parar uma estação em execução
stop_all_stations	Parar todas as estações em execução imediatamente
set_rain_delay	Definir atraso de chuva em horas (0 para limpar)
enable_controller	Habilitar ou desabilitar o controlador
reboot_controller	Reiniciar o controlador OpenSprinkler
view_logs	Obter logs de histórico de irrigação para um intervalo de datas
get_programs	Obter todos os programas de irrigação
get_program	Obter detalhes completos de um único programa por ID
add_program	Adicionar um novo programa de irrigação
delete_program	Excluir um programa de irrigação por ID
get_options	Obter opções e configurações do controlador

---

Configuração

Variáveis de Ambiente

Variável	Descrição	Padrão
OPEN_SPRINKLER_HOST	Nome de host ou endereço IP do OpenSprinkler	localhost
OPEN_SPRINKLER_PASSWORD	Hash MD5 da senha do controlador	(vazio)
OPEN_SPRINKLER_PORT	Número da porta	80
OPEN_SPRINKLER_TLS	Defina como true para usar HTTPS	false
PORT	Porta HTTP para modo SSE	3000
MCP_AUTH_TOKEN	Token Bearer obrigatório em todas as requisições HTTP (opcional)	(não definido — sem autenticação)

Conexão Segura (TLS/HTTPS)

Se o seu OpenSprinkler estiver atrás de um proxy reverso com HTTPS (ex.: nginx, Traefik), defina:

OPEN_SPRINKLER_HOST=opensprinkler.example.com
OPEN_SPRINKLER_PORT=443
OPEN_SPRINKLER_TLS=true

O servidor então se conectará via https://opensprinkler.example.com:443.

Nota: O firmware do OpenSprinkler não suporta TLS nativamente — HTTPS requer um proxy reverso na frente do controlador.

---

Modos de Transporte

O servidor suporta dois modos de transporte, selecionados por um argumento de linha de comando.

stdio (padrão)

Usado quando iniciado diretamente por um cliente MCP (ex.: Claude Desktop). Nenhum argumento necessário:

node dist/index.js

SSE / HTTP (--sse)

Inicia um servidor HTTP que expõe o endpoint MCP via Streamable HTTP (SSE). Use isso quando quiser executar o servidor como um serviço de rede persistente — por exemplo em Docker ou Kubernetes — e conectar-se a ele a partir de múltiplos clientes ou pela rede.

node dist/index.js --sse

O servidor escuta em http://0.0.0.0:${PORT}/mcp (porta padrão 3000).

Conecte seu cliente MCP a: http://<host>:3000/mcp

Autenticação Bearer (somente modo HTTP)

Defina MCP_AUTH_TOKEN para exigir um token bearer em cada requisição HTTP. Se a variável não estiver definida, o servidor aceita todas as conexões (útil para redes privadas ou uso local).

MCP_AUTH_TOKEN=mysecrettoken TRANSPORT=http node dist/index.js

Os clientes devem enviar o cabeçalho:

Authorization: Bearer mysecrettoken

Requisições sem um token válido recebem 401 Unauthorized. O transporte stdio não é afetado — a autenticação não se aplica a ele.

SSE Legado (compatibilidade de backport)

Para testes com ferramentas que implementam o transporte MCP SSE mais antigo (ex.: mcptools, versões mais antigas do inspector), o servidor lida automaticamente com clientes legados no mesmo endpoint /mcp — nenhum flag extra é necessário.

Como o servidor distingue os clientes:

Requisição	Interpretada como
GET /mcp (sem cabeçalho mcp-session-id)	SSE Legado — abre um event-stream
POST /mcp?sessionId=<id>	SSE Legado — cliente enviando uma mensagem
POST /mcp (com ou sem cabeçalho mcp-session-id)	Streamable HTTP moderno

Conectando um cliente legado (exemplo com mcptools):

# Start the server
node dist/index.js --sse

# In another terminal
mcp connect http://localhost:3000/mcp

Nota: SSEServerTransport está obsoleto no SDK MCP e esta camada de compatibilidade destina-se apenas a testes. Clientes de produção devem usar o transporte Streamable HTTP moderno.

Você pode habilitar a saída de debug detalhada durante os testes definindo NODE_ENV=development:

NODE_ENV=development node dist/index.js --sse

Isso imprime cada requisição, status de resposta e evento do ciclo de vida da sessão no stderr.

---

Docker

Consulte docs/docker/ para o guia completo de implantação, arquivo Docker Compose, opções de configuração do Claude Desktop e etapas de solução de problemas.

---

Kubernetes

Consulte docs/kubernetes/ para os manifests. Ajuste o ConfigMap e o Secret para o seu ambiente e então:

kubectl apply -k docs/kubernetes/

---

Claude Desktop (Node.js, sem Docker)

{
  "mcpServers": {
    "opensprinkler": {
      "command": "node",
      "args": ["/path/to/opensprinkler-mcp/dist/index.js"],
      "env": {
        "OPEN_SPRINKLER_HOST": "192.168.1.100",
        "OPEN_SPRINKLER_PASSWORD": "your_password"
      }
    }
  }
}

---

Senha

O firmware do OpenSprinkler armazena qualquer string que foi escrita quando a senha foi definida pela última vez. O aplicativo oficial aplica hash MD5 na senha antes de enviá-la, então o valor armazenado é um hash MD5 — e OPEN_SPRINKLER_PASSWORD deve ser o hash MD5 da sua senha, não o texto simples.

Gere com:

echo -n "your_password" | md5

---

Contribuindo

Contribuições são bem-vindas. Por favor, abra uma issue ou pull request no GitHub.

Agradecimentos

Este projeto é inspirado no trabalho em github.com/Lumeo-sd/opensprinkler-mcp-sdr. Todo o código foi recriado automaticamente do zero usando ferramentas de IA devido à falta de declaração de LICENÇA no repositório original.

Aviso Legal

• Não sou afiliado aos fabricantes, vendedores ou a qualquer uma das marcas dos dispositivos. Este plugin é um projeto pessoal que mantenho no meu tempo livre.
• Consulte a licença para mais informações.