Wakeonlan MCP Server

@cyanheads/wakeonlan-mcp-server Wake LAN machines with Wake-on-LAN magic packets from host profiles, then confirm they came up via MCP. STDIO or Streamable HTTP. 4 Tools

Overview

Wake-on-LAN by name for the machines on your network. Wake a sleeping desktop, GPU box, NAS, or lab machine, wait until it answers on a port like SSH, check whether a host is up without waking it, and troubleshoot a wake that didn't take. Runs on any machine on the same LAN as its hosts.

Tools

Skills

Served over MCP as skill://wakeonlan-guide/SKILL.md and shipped in the npm package under skills/.

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. A wake still ends not_reachable either way; probe.last_outcome and guidance say which, so a wrong check_port can be told apart from 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

1. Navigate into the directory:

cd wakeonlan-mcp-server

1. Install dependencies:

bun install

1. Configure environment:

cp .env.example .env

edit .env and set WOL_HOSTS_FILE or WOL_HOSTS

Configuration

See .env.example for the full list of optional overrides.

Host profiles

Profiles are a JSON array, read once at startup from WOL_HOSTS_FILE or WOL_HOSTS. Set on