wakeonlan-mcp-server

---

概要

ホストプロファイルに登録されたエイリアスを使って、ローカルネットワーク上のマシンをWake-on-LANで起動します。スリープ中のデスクトップ、GPUマシン、NAS、ラボ用マシンを起動し、SSHなどのTCPポートから応答があるまで待機できます。起動せずにホストの稼働状況を確認したり、起動に失敗した場合の対処を進めたりすることもできます。起動対象のホストと同じLANに接続されたマシン上で、STDIOプロセスまたはローカルのStreamable HTTPサーバーとして動作します。

ツール

ツール	説明
wol_wake_host	設定済みのホストにマジックパケットを送信し、TCPチェックポートから応答があるまで待機します
wol_check_host	マジックパケットを送信せず、設定済みホストのチェックポートを1回プローブします
wol_list_hosts	ホストプロファイルと、このマシンが各ホストのサブネットに接続されているかどうかを一覧表示します
wol_list_reference	トピック別のWake-on-LANリファレンスです。パケット形式、ターゲットの設定、電源状態、トラブルシューティング、プロファイル形式、送信側の注意点を確認できます

機能リファレンス

wol_wake_host _ツール

• wol_list_hostsに表示されるalias（大文字と小文字を区別しません）と、任意のwait_for_sを指定します。wait_for_sは0～55秒で、デフォルトは30です。0を指定すると、送信後にチェックせずに戻ります。500 ms間隔で3個のパケットを送信し、送信前にチェックポートを1回プローブします。1個目のパケットを送信した後は2秒ごとにプローブします
• stateはalready_awake、awake（time_to_answer_msを含み、2秒のポーリング間隔を上限とする値）、not_reachable、またはunverified（unverified_reasonはwait_disabledまたはno_address）です。最後の2つには、次の手順を示すguidanceが含まれます
• unknown_host、off_segment（送信なし。このマシンにホストのサブネット上のインターフェースがありません）、再試行可能なwake_in_progress（送信なし。そのホストは別の呼び出しですでに起動中です。1台のホストにつき同時に実行できる起動処理は1つです）、または再試行可能なsocket_errorで失敗します。socket_errorのdataには、失敗したstageとpackets_sentが含まれます

---

wol_check_host _ツール

• alias のみ：プロファイルの address と check_port（プロファイルで別の値が設定されていない限り、22）に対して TCP 接続を 1 回試みます。タイムアウトは 1.5 秒で、マジックパケットは送信しません。ポートは入力項目ではないため、任意のポートをスキャンすることはできません
• outcome は open、refused（マシンは応答したものの、そのポートで待ち受けていません）、または no_answer です。reachable が true になるのは open の場合のみで、latency_ms は open と refused の場合に含まれます
• unknown_host、またはプロファイルに確認対象のアドレスがない場合は no_address として失敗します

---

wol_list_hosts _ツール

• 入力はありません。設定内の順序ですべてのプロファイルを返します：alias、description、mac、address、check_port、wol_port、broadcast と broadcast_source（configured、derived、unresolved のいずれか）、および secureon_set（パスワードは決して含まれません）
• true の場合、送信に使う interface と local_address を含む on_segment は、呼び出しのたびにこのマシンのインターフェースを基に判定されます。何も送信も確認も行わないため、ホストが起動しているかどうかはわかりません
• 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、ブロードキャストアドレス、ポートではありません。そのため、エージェントや HTTP 呼び出し元が Wake や確認を行えるのは、登録されたホストに限られます。SecureOn パスワードはプロファイル内に保持され、返却もログへの記録もされません
• サブネット宛てのブロードキャスト：プロファイルにブロードキャストアドレスが指定されていない場合、ホストの IPv4 アドレスと一致するローカルインターフェースからブロードキャストアドレスを導出します。ローカルサブネット上にないホストには、何も送信する前に拒否を返すため、気付かないうちに別の経路へルーティングされることはありません
• 起動は ICMP ではなく、ホストごとの check_port（デフォルトでは SSH。Windows の場合は RDP または SMB）への TCP 接続で確認します
• LAN レイヤーには Node 標準の node:dgram、node:net、node:os を使用し、サードパーティのネットワーク依存関係はありません

エージェント向けの出力：

• あらゆる待機結果について、エラーではなく結果を返します：state と、呼び出すツールまたはリファレンストピックを示す次の手順 guidance
• 復旧のヒントを含む型付きエラー：unknown_host は設定済みのエイリアスを最大 20 件まで一覧表示し、off_segment は比較したローカルサブネットを示します。macOS では socket_error がローカルネットワークのアクセス許可を案内します
• refused と no_answer を区別します。起動しているものの確認用ポートで待ち受けていないマシンと、一度も応答しなかったマシンは異なる状態として示されるため、誤った check_port が Wake の失敗に見えることはありません

はじめに

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 バンドル（上記のインストールバッジ）は、インストール時にホストファイルまたはインラインのホスト 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+）。
• Wake 対象のホストと同じ LAN セグメントに接続されたマシンが必要です。そのマシンの OS 上でサーバーを実行するか、Linux ではDockerとホストネットワークを使用してください。デフォルトのブリッジネットワーク上のコンテナ、macOS または Windows の Docker Desktop、あるいはデフォルトの NAT モードの WSL2 では、LAN にブロードキャストを送信できません。
• ファームウェアで Wake-on-LAN が有効になっており、OS によって起動可能な状態にされたターゲットが必要です。Windows、Linux、macOS の設定については、topic が prerequisites の wol_list_reference を参照してください。

macOS：ローカルネットワークのアクセス許可

macOS 15 以降では、UDP ブロードキャストの送信や LAN アドレスへの接続にローカルネットワークへのアクセスが必要です。macOS がアクセスを許可するのは node ではなく、サーバーを起動したアプリです。

起動元	アクセス許可を持つアプリ
Claude Desktop（.mcpb バンドルまたは JSON 設定）	Claude Desktop です。macOS は一度だけ確認を求め、許可は起動するすべてのサーバーに適用されます。
Apple のターミナル、または 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）、または 16 進数のみの形式を指定します。グループ（マルチキャスト）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 を指定すると、OS ごとの例を確認できます。

HTTP への公開

起動時のガードにより、認証されていない呼び出し元がこのマシンの外部からツールにアクセスできる 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、LAN アドレスなど）	起動を拒否します	サービスを提供します

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 専用です。ホストを起動できるのは、LAN に接続された Linux マシン上で --network host（または macvlan ネットワーク）を指定して実行した場合のみです。たとえば、すでに Docker を実行している Raspberry Pi、NAS、ホームサーバーなどが該当します。デフォルトのブリッジネットワークでは、コンテナから見えるのは Docker のプライベートサブネットだけなので、wol_wake_host は何も送信する前に off_segment で失敗します。macOS と Windows の Docker Desktop はコンテナを VM 内で実行するため、どのネットワークモードでもブロードキャストは LAN に届きません。

公開されているマルチアーキテクチャイメージ（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() のエントリーポイントです。4 つのツールを登録し、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 とのすべての境界（ソケット、インターフェース、クロック、プラットフォーム、ファイルシステム）は注入可能な接点です。テストでは実際のソケットを開かず、実環境でのチェックはループバック上でのみ実行します

コントリビューション

Issue を歓迎します。提出前にチェックとテストを実行してください：

bun run devcheck
bun run test

ライセンス

このプロジェクトは Apache 2.0 License の下でライセンスされています。詳細は LICENSE ファイルを参照してください。