windows-host-mcp

An MCP server that runs on Linux and gives an MCP agent (e.g. Claude Code) SSH access to a Windows machine — to build, test, run commands, transfer files, and drive long-running or interactive jobs.

┌──────────────┐   MCP (stdio)   ┌──────────────────┐   SSH / SFTP   ┌────────────────┐
│  Claude Code  │ ◄────────────► │ windows-host-mcp  │ ◄────────────► │ Windows machine │
│   (agent)     │                │  (this server)    │                │ (OpenSSH Server)│
└──────────────┘                 └──────────────────┘                 └────────────────┘

Multiple hosts / devices

The server can manage several Windows hosts at once — e.g. a CUDA box and a ROCm box. Each host is defined in a JSON config with capability labels, and each keeps its own SSH connection, session (cwd/env), and jobs. The agent picks a device with list_hosts + use_host, or targets any host per call via the host parameter.

• list_hosts — see every host, its labels (cuda, rocm, …), which is active, and whether it's connected.
• use_host — switch the active device by name or by a label (e.g. { "label": "cuda" }).
• Every command/file/job tool takes an optional host to override the active one for a single call.

Point the server at a JSON file with WINDOWS_HOSTS_CONFIG (see hosts.example.json). A single host can still be configured with the flat WINDOWS_SSH_* env vars instead.

Tools

Tool	Purpose
list_hosts / use_host	List devices and switch the active host (by name or capability label).
test_connection	Verify SSH and report hostname + user. Run this first.
run_command	Run a one-shot command, wait, return stdout/stderr/exit code.
start_job	Start a long-running / interactive command; returns a jobId.
get_job_output	Poll new output (pass sinceOffset) + status + exit code.
send_job_input	Write to a running job's stdin (answer prompts, drive a REPL).
cancel_job	Stop a running job.
list_jobs	List jobs and their status.
upload_file / download_file	SFTP a file to / from Windows.
list_remote_dir	List a Windows directory.
sync_dir	Recursively copy a directory up (local→remote) or down.
batch_upload / batch_download	Transfer many files (by explicit list, regex, or whole folder) in one zip round-trip, with a write policy for conflicts.
get_session / set_session	Read / set default cwd, env, and shell that persist across calls.

Commands run in PowerShell by default; each command tool accepts a shell of powershell | cmd | bash (WSL / Git-Bash).

Prerequisites

• Linux (this machine): Node.js ≥ 18.
• Windows (target): OpenSSH Server installed and running, with your public key authorized.

Install

Not published to the npm registry — clone and link it instead:

git clone https://github.com/thnak/windows-host-mcp.git
cd windows-host-mcp
git checkout v0.2.0   # pin to a release tag; omit to track main instead
npm install
npm link

npm link puts a windows-host-mcp binary on your PATH (a symlink back to this clone — dist/ is committed to the repo, so no separate build step is required). If npm link fails with an EACCES permission error, npm's global prefix isn't user-writable; the standard fix is to point it at a directory you own, e.g.:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
# add ~/.npm-global/bin to your PATH (e.g. in ~/.bashrc), then re-run npm link

windows-host-mcp update (below) keeps this same checkout current, so there's no separate update mechanism to learn.

Note: npm install -g git+https://... (installing directly from a git URL without cloning) looks like it should work too, but hit real, reproducible corruption in testing on some npm versions — it silently dropped files from dist/ and from a dependency's dist/ during npm's git-dependency packing step. Until that's sorted out, git clone + npm link is the only install path this repo tests and recommends.

CLI commands

Command	Purpose
windows-host-mcp	Run the MCP server over stdio (default — this is what an MCP client invokes).
windows-host-mcp config	Interactive wizard: add/edit/remove hosts in hosts.json, then optionally register/update the server with Claude Code.
windows-host-mcp update	Check GitHub Releases for a newer tag, git checkout it in place, and reinstall dependencies.
windows-host-mcp --version	Print the installed version.
windows-host-mcp --help	Show usage.

windows-host-mcp config is the fastest way to get set up: it prompts for each host's connection details, writes them to hosts.json (default ~/.config/windows-host-mcp/hosts.json, or wherever WINDOWS_HOSTS_CONFIG already points), and then — if the claude CLI is on PATH — offers to run claude mcp add/claude mcp remove for you so Claude Code picks up the change immediately. Re-run it any time to add another host or edit an existing one; it loads whatever's already there. See "Configure the MCP client" below for the manual/scripted equivalent.

Windows setup (one-time)

1. Install & start OpenSSH Server

In an elevated PowerShell on the Windows machine:

Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
Set-Service -Name sshd -StartupType Automatic
Start-Service sshd
# Firewall rule (usually created automatically):
New-NetFirewallRule -Name sshd -DisplayName 'OpenSSH Server (sshd)' `
  -Enabled True -Direction Inbound -Protocol TCP -Action Allow -LocalPort 22

2. Create a key pair (on Linux)

ssh-keygen -t ed25519 -f ~/.ssh/windows_host_ed25519 -C "windows-host-mcp"

This produces ~/.ssh/windows_host_ed25519 (private — point the server at this) and ...pub (public — install on Windows).

3. Authorize the public key on Windows

Copy the contents of the .pub file into the right file on Windows:

• Normal (non-admin) user → C:\Users\<you>\.ssh\authorized_keys
• Administrator account → C:\ProgramData\ssh\administrators_authorized_keys, and fix its ACLs:

# For the administrators file only:
icacls "C:\ProgramData\ssh\administrators_authorized_keys" /inheritance:r `
  /grant "Administrators:F" /grant "SYSTEM:F"

Test from Linux:

ssh -i ~/.ssh/windows_host_ed25519 <user>@<windows-host> hostname

4. (Optional) Make PowerShell the login shell

The server wraps every command in its chosen shell explicitly, so this is optional. If you also want interactive ssh sessions to land in PowerShell:

New-ItemProperty -Path "HKLM:\SOFTWARE\OpenSSH" -Name DefaultShell `
  -Value "C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe" `
  -PropertyType String -Force

Configure the MCP client

windows-host-mcp config (above) does this for you interactively. This section is the manual/scripted equivalent — useful for automation or if you'd rather edit files by hand. There are two ways to configure hosts: the JSON file for multiple hosts, or the flat env vars for a single host. Examples below assume windows-host-mcp is on PATH (via npm link, see Install); without that, replace -- windows-host-mcp with -- node /absolute/path/to/windows-host-mcp/dist/index.js.

Multiple hosts (recommended)

Write a hosts.json (see hosts.example.json) and point WINDOWS_HOSTS_CONFIG at it:

claude mcp add windows-host-mcp -s user \
  --env WINDOWS_HOSTS_CONFIG=/absolute/path/to/hosts.json \
  -- windows-host-mcp

Each host entry accepts: name (required), host (required), username (required), keyPath (required, path to the private key on Linux), and optional port, keyPassphrase, shell (powershell|cmd|bash), cwd, labels (capability tags), description, readyTimeoutMs. The top-level defaultHost chooses which host is active on startup (defaults to the first).

Single host (env vars)

For Claude Code:

claude mcp add windows-host-mcp -s user \
  --env WINDOWS_SSH_HOST=192.168.1.50 \
  --env WINDOWS_SSH_USER=builder \
  --env WINDOWS_SSH_KEY_PATH=/home/you/.ssh/windows_host_ed25519 \
  --env WINDOWS_SSH_DEFAULT_SHELL=powershell \
  -- windows-host-mcp

Or as raw MCP JSON config:

{
  "mcpServers": {
    "windows-host-mcp": {
      "command": "windows-host-mcp",
      "env": {
        "WINDOWS_SSH_HOST": "192.168.1.50",
        "WINDOWS_SSH_PORT": "22",
        "WINDOWS_SSH_USER": "builder",
        "WINDOWS_SSH_KEY_PATH": "/home/you/.ssh/windows_host_ed25519",
        "WINDOWS_SSH_DEFAULT_SHELL": "powershell",
        "WINDOWS_SSH_DEFAULT_CWD": "C:\\build"
      }
    }
  }
}

Configuration reference

Variable	Required	Default	Description
WINDOWS_HOSTS_CONFIG	—	—	Path to a multi-host JSON file. If set, the WINDOWS_SSH_* vars below are ignored.
WINDOWS_SSH_HOST	yes*	—	Windows host name or IP.
WINDOWS_SSH_PORT	no	22	SSH port.
WINDOWS_SSH_USER	yes	—	SSH user on Windows.
WINDOWS_SSH_KEY_PATH	yes	—	Path (on Linux) to the private key.
WINDOWS_SSH_KEY_PASSPHRASE	no	—	Passphrase for the private key, if any.
WINDOWS_SSH_DEFAULT_SHELL	no	powershell	powershell | cmd | bash.
WINDOWS_SSH_DEFAULT_CWD	no	—	Default working directory on Windows.
WINDOWS_SSH_READY_TIMEOUT_MS	no	20000	SSH handshake timeout.
WINDOWS_SSH_HOST_NAME	no	default	Display name for the single env-configured host.
WINDOWS_SSH_LABELS	no	—	Comma-separated capability labels for the single host.

* Required only when WINDOWS_HOSTS_CONFIG is not set. See .env.example and hosts.example.json.

Try it

Inspect the tools interactively with the MCP Inspector (env vars must be set in your shell):

npm run inspect

Typical agent flow:

1. list_hosts → see devices; use_host { "label": "cuda" } → target the CUDA box.
2. test_connection → confirms hostname + user.
3. set_session { "cwd": "C:\\src\\MyApp" } → work from one directory.
4. run_command { "command": "nvidia-smi" }.
5. start_job { "command": "dotnet build MyApp.sln" } → poll get_job_output until status: exited.
6. download_file { "remotePath": "C:/src/MyApp/bin/Release/app.zip", "localPath": "/tmp/app.zip" }.
7. use_host { "label": "rocm" } → run the same build on the ROCm box (its own session & jobs).

Notes & caveats

• One host per server instance. To reach several Windows machines, register multiple instances with different names/env.
• Signals on Windows OpenSSH are unreliable. cancel_job sends a signal and closes the channel; for a stubborn process, run taskkill /PID <pid> /F (or /IM <image>) via run_command.
• pty: true allocates a terminal (needed for programs that demand a TTY / interactive prompts) but merges stdout and stderr; leave it off for clean build logs.
• Output is capped (~1 MB per stream for run_command, ~5 MB buffered per job) to protect the agent's context; truncation is flagged in the result.
• batch_upload zips the selected files locally, sends them in one SFTP transfer, and unpacks with PowerShell's built-in Expand-Archive — no extra tooling needed on either side. Select files via files (explicit relative paths), pattern (regex over paths relative to localDir), or neither (whole folder, recursive by default). writePolicy controls collisions with existing remote files: overwrite (default) always replaces, keep-newer replaces only if the local file's mtime is newer (zip timestamps have ~2s resolution), skip-existing never touches an existing file.
• batch_download is the mirror: files are selected and zipped on the Windows host with PowerShell's built-in Compress-Archive, pulled down in one SFTP transfer, and unpacked here. Same files / pattern / whole-folder selection (relative to remoteDir this time) and the same writePolicy semantics, applied to local files instead of remote ones.
• Secrets: the private key stays on Linux; only its path is passed via env. Keep keys out of the repo (.gitignore covers *.key, id_*, .env).
• Updating: run windows-host-mcp update — it checks GitHub Releases for a newer tag, then runs git fetch/git checkout <tag>/npm install in your existing clone (the same one npm link pointed the binary at). Restart (or reconnect) any running MCP client session afterward so it picks up the new build.

Development

npm run dev     # tsx watch mode
npm run check   # type-check only
npm run build   # emit dist/