OPenSprinkler MCP Server

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

Documentação

Servidor MCP OpenSprinkler

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 do 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`
`OPEN_SPRINKLER_TIMEOUT_MS`	Abortar uma solicitação do controlador após este número de milissegundos	`10000`
`PORT`	Porta HTTP para modo SSE	`3000`
`HOST`	Interface para vincular no modo SSE. Use `127.0.0.1` para aceitar apenas conexões locais	`0.0.0.0`
`MCP_AUTH_TOKEN`	Token Bearer exigido em todas as solicitações HTTP (opcional)	(não definido — sem autenticação)
`MCP_ALLOWED_HOSTS`	Lista de permissões do cabeçalho `Host` separada por vírgulas. Quando definida, outros hosts recebem `403` — isso é o que bloqueia ataques de rebinding de DNS	(não definido — não validado)
`MCP_ALLOWED_ORIGINS`	Lista de permissões `Origin` separada por vírgulas para clientes de navegador. Solicitações sem `Origin` não são afetadas	(não definido — não validado)

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 vários clientes ou pela rede.

node dist/index.js --sse

O servidor escuta em http://${HOST}:${PORT}/mcp (padrão 0.0.0.0: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 solicitaçã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

Solicitações sem um token válido recebem 401 Unauthorized. Os tokens são comparados em tempo constante. O transporte stdio não é afetado — a autenticação não se aplica lá.

Reforço de Rede (somente modo HTTP)

Essas ferramentas podem iniciar e parar a irrigação, desabilitar o controlador, reiniciá-lo e excluir programas, então qualquer pessoa que possa alcançar a porta HTTP pode fazer tudo isso. No modo HTTP, o servidor vincula 0.0.0.0 por padrão e imprime um aviso na inicialização quando nenhum token está definido.

Para qualquer coisa além de uma rede privada confiável:

MCP_AUTH_TOKEN=mysecrettoken \
HOST=127.0.0.1 \
MCP_ALLOWED_HOSTS=localhost:3000,127.0.0.1:3000 \
node dist/index.js --sse

MCP_AUTH_TOKEN é o controle principal — sem ele, o endpoint fica aberto.
MCP_ALLOWED_HOSTS defende contra rebinding de DNS: uma página da web maliciosa pode fazer um navegador na sua rede alcançar 127.0.0.1:3000, mas a solicitação ainda carrega o nome do host do atacante no cabeçalho Host, que a lista de permissões rejeita.
HOST=127.0.0.1 mantém o listener fora da rede completamente. Deixe-o no padrão 0.0.0.0 dentro de Docker/Kubernetes, onde o contêiner precisa aceitar conexões de fora do seu namespace de rede.

SSE Legado (compatibilidade reversa)

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

Como o servidor distingue clientes:

Solicitação	Interpretada como
`GET /mcp` (sem cabeçalho `mcp-session-id`)	SSE legado — abre um fluxo de eventos
`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 ativar a saída de depuração detalhada durante os testes definindo NODE_ENV=development:

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

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

Docker

Consulte docs/docker/ para o guia de implantação completo, 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, em seguida:

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-o 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 qualquer uma das marcas de dispositivos. Este plugin é um projeto pessoal que mantenho no meu tempo livre.
Consulte a licença para mais informações.