@cyanheads/wakeonlan-mcp-server

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

Related MCP server: synapse-rmcp

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

2. Navigate into the directory:

cd wakeonlan-mcp-server

3. Install dependencies:

bun install

4. 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 one of the two: both set is a startup error, and neither set starts the server with no hosts, which wol_list_hosts explains. WOL_HOSTS_FILE must be absolute (after ~/ expansion), because a stdio server runs in the MCP client's working directory, and must name a regular file of at most 1 MiB: a directory, a pipe, or a device such as /dev/stdin is a startup error. Editing the profiles takes a restart.

[
  {
    "alias": "gpu-box",
    "description": "Desktop with the training GPU; SSH on 22.",
    "mac": "00:00:5e:00:53:01",
    "address": "192.0.2.50"
  },
  {
    "alias": "nas",
    "mac": "00-00-5E-00-53-02",
    "address": "nas.home.arpa",
    "broadcast": "192.0.2.255",
    "check_port": 445,
    "secureon": "00:00:5e:00:53:ff"
  }
]

An empty string leaves an optional text field (address, broadcast, secureon, description) unset. The server refuses to start, naming the entry and field, on an unknown key, an invalid value, a duplicate alias, or a profile with neither broadcast nor an IPv4 address. Whether this machine sits on a host's subnet is checked per call, not at startup, since interfaces change. wol_list_reference with topic host-profiles has an example per OS.

HTTP exposure

A startup guard refuses any HTTP deployment that would let an unauthenticated caller reach the tools from beyond this machine, or from a web page through your browser. Stdio is unaffected.

DEV_MCP_AUTH_BYPASS counts as unauthenticated. With MCP_ALLOWED_ORIGINS unset, requests from non-loopback browser origins are rejected, so a web page can't drive a loopback endpoint through DNS rebinding; * turns that check off, which is why it needs auth. Host profiles are server-wide: every authenticated caller can wake the same hosts.

Running the server

Local development

• Build and run the production version:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio

• Run checks and tests:

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite

Docker

The image is Linux-only. It can wake hosts only when run with --network host (or on a macvlan network) on a Linux machine attached to their LAN, such as a Raspberry Pi, NAS, or home server that already runs Docker. On a default bridge network the container sees only Docker's private subnet, so wol_wake_host fails with off_segment before sending anything. Docker Desktop on macOS and Windows runs containers in a VM, so its broadcasts can't reach the LAN in any network mode.

Build the image from a clone of this repository:

docker build -t wakeonlan-mcp-server .

Then add it to your MCP client configuration on that machine. The hosts file is mounted read-only from an absolute host path, and WOL_HOSTS_FILE names where it sits inside the container:

{
  "mcpServers": {
    "wakeonlan-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--network", "host",
        "-v", "/path/to/hosts.json:/etc/wakeonlan/hosts.json:ro",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "WOL_HOSTS_FILE=/etc/wakeonlan/hosts.json",
        "wakeonlan-mcp-server"
      ]
    }
  }
}

The container runs as the image's bun user (uid 1000), which must be able to read the hosts file. Without MCP_TRANSPORT_TYPE=stdio the image serves Streamable HTTP on port 3010, bound to loopback, which under host networking is the host's own; any other bind needs MCP_AUTH_MODE jwt or oauth (see HTTP exposure). Logs go to /var/log/wakeonlan-mcp-server. OpenTelemetry peer dependencies are installed by default; build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic

• Use ctx.log for request-scoped logging; nothing persists, so ctx.state goes unused

• Register new tools in the createApp() arrays in src/index.ts

• Every OS boundary (sockets, interfaces, clock, platform, filesystem) is an injected seam: tests never open a real socket, and live checks run on loopback only

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.