Overview

Wake-on-LAN for the machines on your local network, addressed by the aliases in your host profiles. Wake a sleeping desktop, GPU box, NAS, or lab machine, wait until it answers on a TCP port such as SSH, check whether a host is up without waking it, and work through a wake that didn't take. Runs as a stdio process or a local Streamable HTTP server on a machine attached to the same LAN as the hosts it wakes.

Tools

Capability reference

wol_wake_host _tool

• alias (from wol_list_hosts, case-insensitive) plus optional wait_for_s, 0–55 seconds, default 30; 0 sends and returns without checking. Sends 3 packets 500 ms apart, probing the check port once before sending and every 2 s after the first packet
• state is already_awake, awake (with time_to_answer_ms, an upper bound at the 2 s poll interval), not_reachable, or unverified (unverified_reason: wait_disabled or no_address); the last two carry a guidance next step
• Fails as unknown_host, off_segment (nothing sent: this machine has no interface on the host's subnet), retryable wake_in_progress (nothing sent: another call is already waking that host, and one wake per host runs at a time), or retryable socket_error, whose data carries the failed stage and packets_sent

wol_check_host _tool

• alias only: one TCP connect to the profile's address and check_port (22 unless the profile sets another), 1.5 s timeout, no magic packet. The port is not an input, so the tool can't scan arbitrary ports
• outcome is open, refused (the machine answered, nothing listens on that port), or no_answer; reachable is true only for open, and latency_ms is present for open and refused
• Fails as unknown_host, or no_address when the profile has no address to probe

wol_list_hosts _tool

• No input. Returns every profile in config order: alias, description, mac, address, check_port, wol_port, broadcast with broadcast_source (configured, derived, or unresolved), and secureon_set (never the password)
• on_segment, with the sending interface and local_address when true, is resolved against this machine's interfaces on every call; nothing is sent or probed, so it says nothing about whether a host is up
• config_source (file, inline, or none) and config_path name where the profiles came from

wol_list_reference _tool

• topic: packet-format, prerequisites, sleep-states, troubleshooting, host-profiles, or sender-environment
• Static markdown with no network access; every response lists all topics for navigation

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

Wake-on-LAN-specific:

• Operator-configured targets only: callers pass an alias, never a MAC, IP, broadcast address, or port, so an agent or HTTP caller can wake and probe only the hosts you listed. SecureOn passwords stay in the profile, never returned or logged
• Subnet-directed broadcasts: the broadcast address is derived from a host's IPv4 address and the matching local interface when the profile omits it, and a host on no local subnet is refused before anything is sent instead of being routed away silently
• Wakes are confirmed by a TCP connect to a per-host check_port (SSH by default; RDP or SMB for Windows), not ICMP
• The LAN layer is Node's own node:dgram, node:net, and node:os, with no third-party networking dependency

Agent-friendly output:

• Results, not errors, for every wait outcome: state plus a guidance next step naming the tool or reference topic to call
• Typed failures with recovery hints: unknown_host lists up to 20 configured aliases, off_segment names the local subnets it compared, and on macOS socket_error points at the Local Network permission
• refused vs no_answer: a machine that is on but not listening on its check port reads differently from one that never answered, so a wrong check_port doesn't look like a failed wake

Getting started

Add the following to your MCP client configuration file, pointing WOL_HOSTS_FILE at your hosts file.

{
  "mcpServers": {
    "wakeonlan-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/wakeonlan-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "WOL_HOSTS_FILE": "~/.config/wakeonlan/hosts.json"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "wakeonlan-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/wakeonlan-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "WOL_HOSTS_FILE": "~/.config/wakeonlan/hosts.json"
      }
    }
  }
}

The Claude Desktop .mcpb bundle (the install badge above) asks for a hosts file or inline hosts JSON when you install it.

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 WOL_HOSTS_FILE=~/.config/wakeonlan/hosts.json bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.4.0 or higher (or Node.js v24+).
• A machine attached to the same LAN segment as the hosts it wakes. Run the server on that machine's OS, or in Docker with host networking on Linux: a container on a default bridge network, Docker Desktop on macOS or Windows, or WSL2 in its default NAT mode can't put a broadcast on the LAN.
• Targets with Wake-on-LAN enabled in firmware and armed by the OS. wol_list_reference with topic prerequisites has the Windows, Linux, and macOS settings.

macOS: Local Network permission

On macOS 15 and later, sending a UDP broadcast or connecting to a LAN address needs Local Network access, and macOS grants it to the app that launched the server rather than to node:

Grant or check it under System Settings > Privacy & Security > Local Network. The first send can fail while the alert is pending, so wol_wake_host may return socket_error; retry after allowing. If that list shows a node entry rather than your client app, enable the node entry. A denied permission also makes wol_check_host read no_answer. Windows and Linux have no per-app gate. wol_list_reference with topic sender-environment covers the rest, including the macOS 15.5+ subnet exemption.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/wakeonlan-mcp-server.git