wakeonlan-mcp-server

---

概述

为本地网络中的机器提供 Wake-on-LAN 功能，并通过主机配置文件中的别名指定目标。唤醒休眠的台式机、GPU 主机、NAS 或实验室机器，等待其在 SSH 等 TCP 端口上响应；无需唤醒即可检查主机是否在线，也可排查唤醒失败的情况。可作为 stdio 进程运行，也可作为本地 Streamable HTTP 服务运行；运行机器必须与要唤醒的主机连接到同一局域网。

工具

工具	说明
wol_wake_host	向配置的主机发送魔术数据包，然后等待其 TCP 检查端口响应
wol_check_host	探测配置主机的检查端口一次，不发送魔术数据包
wol_list_hosts	列出主机配置文件，并显示本机是否连接到每台主机所在的子网
wol_list_reference	按主题提供 Wake-on-LAN 参考信息：数据包格式、目标设备设置、电源状态、故障排除、配置文件格式、发送端注意事项

功能参考

wol_wake_host _工具

• alias（来自 wol_list_hosts，不区分大小写），以及可选的 wait_for_s，范围为 0–55 秒，默认为 30；0 表示发送后立即返回，不进行检查。以 500 ms 间隔发送 3 个数据包；发送前探测一次检查端口，发送第一个数据包后每 2 s 探测一次
• state 为 already_awake、awake（带有 time_to_answer_ms，其上限为 2 s 的轮询间隔）、not_reachable 或 unverified（unverified_reason 为 wait_disabled 或 no_address）；后两种状态会附带下一步 guidance
• 失败状态包括 unknown_host、off_segment（未发送任何内容：本机没有连接到主机所在子网的网络接口）、可重试的 wake_in_progress（未发送任何内容：另一个调用正在唤醒该主机，每台主机一次只能执行一个唤醒任务），或可重试的 socket_error，其 data 包含失败的 stage 和 packets_sent

wol_check_host _工具

• 仅接受 alias：向配置文件中的 address 和 check_port 发起一次 TCP 连接（除非配置文件另有设置，否则为 22），超时时间为 1.5 秒，不发送魔术包。端口不是输入参数，因此该工具无法扫描任意端口
• outcome 为 open、refused（机器已响应，但该端口没有程序监听）或 no_answer；只有 open 时 reachable 才为 true，open 和 refused 时会提供 latency_ms
• 若主机未知，则返回 unknown_host；若配置文件中没有可供探测的地址，则返回 no_address

---

wol_list_hosts _工具

• 无输入。按配置顺序返回每个配置文件：alias、description、mac、address、check_port、wol_port、broadcast 及其 broadcast_source（configured、derived 或 unresolved），还有 secureon_set（绝不返回密码）
• 每次调用时都会根据本机网络接口解析 on_segment；当其为 true 时，还会提供发送用的 interface 和 local_address。此工具不会发送或探测任何内容，因此无法说明主机是否已启动
• config_source（file、inline 或 none）和 config_path 会指出配置文件的来源位置

---

wol_list_reference _工具

• topic：packet-format、prerequisites、sleep-states、troubleshooting、host-profiles 或 sender-environment
• 静态 Markdown，不访问网络；每个响应都会列出所有 topics 以供导航

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志记录。

Wake-on-LAN 专属功能：

• 仅限操作员配置的目标：调用方只能传入别名，不能传入 MAC、IP、广播地址或端口，因此 Agent 或 HTTP 调用方只能唤醒和探测你列出的主机。SecureOn 密码保留在配置文件中，绝不返回或记录到日志
• 定向子网广播：若配置文件中未指定广播地址，则根据主机的 IPv4 地址和匹配的本地接口推导；若主机不在任何本地子网上，则会在发送任何内容之前拒绝操作，而不是悄然将请求路由到别处
• 通过向每台主机的 check_port 发起 TCP 连接来确认唤醒（默认为 SSH；Windows 可用 RDP 或 SMB），而非使用 ICMP
• 局域网层使用 Node 自带的 node:dgram、node:net 和 node:os，不依赖第三方网络库

便于 Agent 使用的输出：

• 无论等待结果如何，都会返回结果而非错误：包含 state 以及 guidance 后续步骤，指明要调用的工具或参考主题
• 类型化失败并附带恢复提示：unknown_host 会列出最多 20 个已配置别名，off_segment 会指出用于比较的本地子网；在 macOS 上，socket_error 会提示检查“本地网络”权限
• 区分 refused 和 no_answer：已开机但未监听检查端口的机器，与从未响应的机器显示不同，因此错误的 check_port 不会被误认为唤醒失败

开始使用

将以下内容添加到 MCP 客户端配置文件，并将 WOL_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"
      }
    }
  }
}

也可使用 npx（无需 Bun）：

{
  "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"
      }
    }
  }
}

安装 Claude Desktop .mcpb bundle（上方的安装徽章）时，系统会要求你提供主机文件或内联主机 JSON。

对于 Streamable HTTP，设置传输方式并启动服务：

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

先决条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 运行服务的机器必须与待唤醒主机连接到同一局域网网段。请在该机器的操作系统上运行服务，或在 Linux 上通过Docker 使用 host networking：默认桥接网络中的容器、macOS 或 Windows 上的 Docker Desktop，以及默认 NAT 模式下的 WSL2，均无法向局域网发送广播。
• 目标设备必须在固件中启用 Wake-on-LAN，并由操作系统设置为可唤醒。使用主题为 prerequisites 的 wol_list_reference 查看 Windows、Linux 和 macOS 的设置。

macOS：本地网络权限

在 macOS 15 及更高版本中，发送 UDP 广播或连接到局域网地址需要本地网络访问权限；macOS 会将权限授予启动服务的应用，而不是 node：

启动来源	获得权限的对象
Claude Desktop（.mcpb 捆绑包或 JSON 配置）	Claude Desktop。macOS 会询问一次，授予的权限适用于它启动的所有服务。
Apple 的 Terminal 或 SSH 会话	自动允许，不会弹出提示。
第三方终端或编辑器（iTerm2、Ghostty、VS Code、Cursor 等）	对应应用会收到权限提示。
launchd 守护进程或以 root 身份运行的进程	自动允许。
launchd 代理	在授予权限前会被阻止。请改为将常驻服务作为守护进程运行。

在系统设置 > 隐私与安全性 > 本地网络中授予或检查权限。权限提示尚未处理时，首次发送可能会失败，因此 wol_wake_host 可能返回 socket_error；允许后请重试。如果列表中显示的是 node 条目，而不是你的客户端应用，请启用 node 条目。拒绝权限也会导致 wol_check_host 返回 no_answer。Windows 和 Linux 没有针对单个应用的权限限制。wol_list_reference 的 sender-environment 主题还介绍了其余相关信息，包括 macOS 15.5 及更高版本的子网豁免。

安装

1. 克隆仓库：

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

2. 进入目录：

cd wakeonlan-mcp-server

3. 安装依赖项：

bun install

4. 配置环境：

cp .env.example .env
# edit .env and set WOL_HOSTS_FILE or WOL_HOSTS

配置

变量	说明	默认值
WOL_HOSTS_FILE	JSON 主机文件的绝对路径；以 ~/ 开头的路径会展开为主目录路径。不能与 WOL_HOSTS 同时使用。	无
WOL_HOSTS	内联填写相同的 JSON 数组，适用于单主机配置或不便使用文件的客户端。不能与 WOL_HOSTS_FILE 同时使用。	无
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_HOST	HTTP 绑定地址。除回环地址外，其他地址都需要将 MCP_AUTH_MODE 设为 jwt 或 oauth。	127.0.0.1
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_AUTH_MODE	身份验证方式：none、jwt 或 oauth。	none
MCP_ALLOWED_ORIGINS	HTTP 端点允许的浏览器来源，以逗号分隔。未启用 jwt 或 oauth 时，不允许使用 *。	回环来源
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto。	stateless
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<app-root>/logs
OTEL_ENABLED	启用 OpenTelemetry。	false

完整的可选覆盖项列表请参阅 .env.example。

主机配置

配置文件是一个 JSON 数组，在启动时从 WOL_HOSTS_FILE 或 WOL_HOSTS 读取。必须设置其中一个：两者都设置会导致启动错误；两者都未设置时，服务器启动后不会配置任何主机，wol_list_hosts 会对此作出说明。WOL_HOSTS_FILE 必须是绝对路径（展开 ~/ 后），因为 stdio 服务器运行在 MCP 客户端的工作目录中；该路径还必须指向一个不超过 1 MiB 的常规文件：目录、管道或 /dev/stdin 之类的设备都会导致启动错误。编辑配置文件后必须重启。

[
  {
    "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"
  }
]

字段	必填	默认值	规则
alias	是		1–64 个字符：以字母或数字开头，后续可使用字母、数字、.、_ 或 -。不区分大小写，且必须唯一。
mac	是		支持冒号、连字符、Cisco 点分形式（0000.5e00.5301）或纯十六进制形式。拒绝组播 MAC 地址和全零 MAC 地址。
address	否		IPv4 或 IPv6 字面地址，或 DNS 主机名。探测目标：不填写时无法确认主机是否已唤醒，且 wol_check_host 会拒绝该主机。
broadcast	除非 address 为 IPv4，否则必填	自动推导	子网的定向广播地址。拒绝 255.255.255.255、0.0.0.0 和 224.0.0.0/4。
wol_port	否	9	UDP 目标端口，范围为 1–65535。
check_port	否	22	用于探测主机是否已启动的 TCP 端口，范围为 1–65535。Windows 主机通常需要使用 3389（RDP）或 445（SMB）。
secureon	否		MAC 格式的 6 字节 SecureOn 密码。绝不显示或记录。
description	否		操作员备注，最多 500 个字符，由 wol_list_hosts 返回。

空字符串会将可选文本字段（address、broadcast、secureon、description）视为未设置。遇到未知键、无效值、重复别名，或既未设置 broadcast 也未设置 IPv4 address 的配置时，服务器会拒绝启动，并指出对应的条目和字段。此机器是否位于主机所在子网，会在每次调用时检查，而非启动时检查，因为网络接口可能会发生变化。wol_list_reference 使用主题 host-profiles 时会提供各操作系统的示例。

HTTP 暴露

启动保护机制会拒绝任何可能让未认证调用者从本机以外访问工具，或通过浏览器中的网页访问工具的 HTTP 部署。Stdio 不受影响。

MCP_HTTP_HOST	未认证（MCP_AUTH_MODE=none）	jwt 或 oauth
回环地址：localhost、127.0.0.0/8、::1	提供服务，除非 MCP_ALLOWED_ORIGINS 包含 *	提供服务
其他地址（0.0.0.0、局域网地址等）	拒绝启动	提供服务

DEV_MCP_AUTH_BYPASS 也视为未认证。未设置 MCP_ALLOWED_ORIGINS 时，会拒绝来自非回环浏览器来源的请求，因此网页无法通过 DNS 重绑定驱动回环端点；* 会关闭这项检查，所以必须启用身份验证。主机配置对整个服务器生效：每个通过身份验证的调用者都可以唤醒相同的主机。

运行服务器

本地开发

• 构建并运行生产版本：

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

• 运行检查和测试：

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

Docker

该镜像仅支持 Linux。只有在连接到相应局域网的 Linux 机器上使用 --network host（或 macvlan 网络）运行时，才能唤醒主机；例如已运行 Docker 的 Raspberry Pi、NAS 或家用服务器。在默认桥接网络中，容器只能看到 Docker 的专用子网，因此 wol_wake_host 会在发送任何数据前因 off_segment 失败。macOS 和 Windows 上的 Docker Desktop 会在虚拟机中运行容器，因此无论采用哪种网络模式，其广播都无法抵达局域网。

拉取已发布的多架构镜像（linux/amd64、linux/arm64）：

docker pull ghcr.io/cyanheads/wakeonlan-mcp-server:latest

或者从本仓库克隆版本构建镜像：docker build -t ghcr.io/cyanheads/wakeonlan-mcp-server:latest .。然后在该机器上的 MCP 客户端配置中添加此镜像。以只读方式挂载的主机文件必须使用主机上的绝对路径，而 WOL_HOSTS_FILE 用于指定该文件在容器内的位置：

{
  "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",
        "ghcr.io/cyanheads/wakeonlan-mcp-server:latest"
      ]
    }
  }
}

容器以镜像中的 bun 用户（uid 1000）运行，该用户必须能够读取主机文件。不设置 MCP_TRANSPORT_TYPE=stdio 时，镜像会在端口 3010 上提供 Streamable HTTP 服务，并绑定到环回地址；使用主机网络时，该地址就是主机自身。任何其他绑定方式都需要设置 MCP_AUTH_MODE 为 jwt 或 oauth（参见 HTTP 暴露）。日志写入 /var/log/wakeonlan-mcp-server。默认会安装 OpenTelemetry 对等依赖；构建时添加 --build-arg OTEL_ENABLED=false 可省略这些依赖。

项目结构

目录	用途
src/index.ts	createApp() 入口：注册四个工具、运行 HTTP 暴露防护，并加载主机配置文件。
src/config	解析 WOL_HOSTS_FILE / WOL_HOSTS，以及 HTTP 暴露防护。
src/mcp-server/tools	工具定义（*.tool.ts）、共享的 alias 输入，以及静态参考主题。
src/services/hosts	加载和验证主机配置文件、解析 MAC 地址，以及查找别名。
src/services/lan	构造魔术数据包、解析子网、发送 UDP 数据，以及进行 TCP 探测。
tests/	针对模拟套接字的单元、集成和模糊测试，结构与 src/ 一致。

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简要说明如下：

• 处理程序抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围内的日志；没有持久化内容，因此不使用 ctx.state
• 在 src/index.ts 的 createApp() 数组中注册新工具
• 每个 OS 边界（套接字、接口、时钟、平台、文件系统）都通过注入点隔离：测试不会打开真实套接字，实时检查仅在环回地址上运行

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

本项目采用 Apache 2.0 许可证。详情请参阅 LICENSE 文件。