0.2.1 • Published 3d agoCLI

winreach-mcp

Licence

MIT

Version

0.2.1

Deps

Size

145 kB

Vulns

Weekly

Stars

Summary Dependency Versions

WinReach MCP

Give your AI agent its own Windows machine. Remote PowerShell, file transfer, screenshots, and full desktop control (computer use — mouse & keyboard) over HTTP — secured with per-user keys, roles, command policies, mTLS, and an audit log.

WinReach is a TypeScript Model Context Protocol server that runs on a Windows host and exposes it to AI agents over Streamable HTTP. Where most Windows MCP servers run locally over stdio on the user's own machine, WinReach is remote-first and secured: Codex, Claude Code, and other MCP-capable agents can run PowerShell, move files, capture the screen, and drive the mouse and keyboard on a Windows box from anywhere — each with its own bearer key, role, and command policy, every action written to an audit log, and a one-command Cloudflare tunnel to publish it with no inbound firewall hole.

Agent or MCP client  ->  WinReach MCP over HTTP  ->  Windows (PowerShell + desktop)

Demo

Connect an agent over HTTP, run remote PowerShell, drive the Windows desktop, and keep every action behind per-user keys — in about 30 seconds.

Watch the full-quality MP4 · built with Remotion (source and re-render steps in video/).

There's also a vertical 4:5 LinkedIn cut with burned-in captions — assets/winreach-linkedin.mp4 (cover: assets/winreach-linkedin-cover.png, captions: assets/winreach-linkedin.srt).

Why WinReach?

Most coding agents are comfortable in terminals, but Windows RDP is a GUI-first environment. WinReach gives agents a clean command surface instead:

Run PowerShell commands on a Windows host from any MCP client.
Keep persistent PowerShell sessions when variables, cwd, or imported modules matter.
Publish the server to your agent in one command with a built-in Cloudflare tunnel — no fixed public IP, no inbound firewall hole.
Use bearer-token auth and provider firewalls instead of exposing raw RDP workflows.
Test locally with a diagnostic client before connecting a real agent.
Avoid IIS: WinReach is a standalone Node HTTP server.

Install & Connect (npx)

No clone, no build. WinReach ships as an npm package with a winreach-mcp binary.

1. Generate a token:

npx winreach-mcp gen-token
# -> a fresh random bearer token, e.g. 9V4P3Am6EjKsMJVetyrl-s60NVcP_MmDvsP_gFgcq3U

2a. Local, zero-config (stdio) — fastest path. Any stdio MCP client can launch WinReach directly on the Windows machine. No HTTP, no tunnel, no token wrangling (an ephemeral admin token is minted if you don't set one):

{
  "mcpServers": {
    "winreach": {
      "command": "npx",
      "args": ["-y", "winreach-mcp", "--stdio"]
    }
  }
}

2b. Remote (HTTP + bearer token). Run the server on the Windows host and connect agents over the network (optionally via the built-in Cloudflare tunnel):

$env:WINREACH_TOKEN = "PASTE_TOKEN_FROM_STEP_1"
npx winreach-mcp            # add --tunnel to publish a public Cloudflare URL

Copy-paste snippets for Claude Code, Claude Desktop, Codex, and Cursor (both local stdio and remote HTTP forms), plus the Claude Desktop one-click extension, are in docs/CONNECT.md.

The winreach-mcp CLI:

Command	What it does
`npx winreach-mcp` (or `start`)	Start the Streamable-HTTP MCP server (default; add `--tunnel` for a public URL).
`npx winreach-mcp --stdio`	Run over the local stdio transport for an MCP client that launches it.
`npx winreach-mcp gen-token`	Print a fresh random bearer token.

Tooling

WinReach exposes up to eight MCP tools (the last three are opt-in):

Tool	Purpose
`powershell_execute`	Run one isolated PowerShell command.
`powershell_open_session`	Start a persistent PowerShell session.
`powershell_send`	Send a command to a persistent session.
`powershell_close_session`	Close a persistent session.
`powershell_list_sessions`	List active sessions.
`take_screenshot`	Capture the current screen of the Windows host as an image. Off by default (see below).
`computer_use`	Control the desktop like a human — move/click the mouse, type text, press key chords, and scroll — via Win32 `SendInput`. Coordinates match `take_screenshot`. Off by default; admin/operator roles recommended (see below).
`file_upload`	Write a file to the host, inside the configured file root. Off by default (see below).
`file_download`	Read a file from the host (optionally moving it) as base64. Off by default (see below).

Command results include:

{
  "commandId": "uuid",
  "stdout": "hello\r\n",
  "stderr": "",
  "exitCode": 0,
  "durationMs": 143,
  "truncated": false
}

take_screenshot captures the full virtual desktop (all monitors) and returns an MCP image block (base64 PNG by default, jpeg optional) alongside a metadata block:

{
  "commandId": "uuid",
  "success": true,
  "format": "png",
  "mimeType": "image/png",
  "width": 1920,
  "height": 1080,
  "bytes": 82344,
  "durationMs": 96
}

Screen capture needs an active interactive desktop session. If WinReach runs in a non-interactive service context (Windows session 0), the capture fails and the tool returns success: false with the PowerShell error instead of an image.

Because screen capture reads whatever is on the desktop, it is a read/exfiltration capability the command policy cannot express, so it is disabled by default. Enable it with WINREACH_ALLOW_SCREENSHOT=1, and optionally restrict it to specific principal roles with WINREACH_SCREENSHOT_ROLES. When disabled (or when the caller's role is not permitted) the tool is not exposed to that principal at all. Captures are written to a server-owned directory (WINREACH_SCREENSHOT_DIR) — callers cannot choose the path — and are automatically deleted after WINREACH_SCREENSHOT_RETENTION_HOURS (default 8) so they do not accumulate on the host.

File transfer

file_upload and file_download move files between the agent and the Windows host over MCP (base64-encoded, SHA-256 returned for integrity). They are off by default and only registered once you set a sandbox root:

$env:WINREACH_FILE_ROOT = "C:\winreach-files"

Every path is relative to WINREACH_FILE_ROOT. Absolute paths, .. traversal, and symlinks that escape the root are rejected, so a transfer can never touch files outside the sandbox. Setting the root is what enables the tools.
file_upload refuses to overwrite unless overwrite: true, and creates parent directories inside the root as needed.
file_download returns the file as base64; set deleteSource: true to move it (the server copy is deleted after a successful read).
Files larger than WINREACH_MAX_FILE_BYTES (default 75 MB) are rejected in either direction.
Every transfer is written to the audit log (tool, principal, server path, size).

Quickstart

Requirements:

Node.js 24 or newer
npm
Windows PowerShell (powershell.exe) or PowerShell 7 (pwsh)

Run WinReach locally:

git clone https://github.com/GhouI/winreach-mcp.git
cd winreach-mcp
npm install
$env:WINREACH_TOKEN = "dev-token"
npm run dev

The server defaults to:

http://127.0.0.1:7573/mcp

Use the diagnostic client from another terminal:

$env:WINREACH_TOKEN = "dev-token"
npm run client -- list-tools
npm run client -- exec Write-Output hello

Target more than one WinReach server with WINREACH_URLS:

$env:WINREACH_TOKEN = "shared-token"
$env:WINREACH_URLS = "http://win-1:7573/mcp,http://win-2:7573/mcp"
npm run client -- exec hostname

Public Access With One Command

When you set up WinReach on a server and want an agent to reach it from anywhere, enable the built-in Cloudflare quick tunnel. WinReach downloads cloudflared on first use (no Cloudflare account needed), opens a tunnel, and prints a ready-to-paste agent config.

$env:WINREACH_TOKEN = "replace-with-a-long-random-token"
$env:WINREACH_TUNNEL = "cloudflare"
npm run dev

Output:

WinReach MCP listening at http://127.0.0.1:7573/mcp
Cloudflare tunnel ready: https://random-words.trycloudflare.com
Public MCP endpoint: https://random-words.trycloudflare.com/mcp

Connect an agent with this public endpoint (the bearer token is still required):

Claude Code:
  claude mcp add --transport http winreach https://random-words.trycloudflare.com/mcp --header "Authorization: Bearer <WINREACH_TOKEN>"
...

You can also enable it ad hoc with a flag:

npm run dev -- --tunnel

Notes:

cloudflared connects to WinReach over loopback, so tunnel mode needs no 0.0.0.0 bind and no inbound firewall rule. WinReach tells cloudflared to rewrite the forwarded Host header to 127.0.0.1 so the server's built-in DNS-rebinding protection keeps working.
Tunnel mode publishes a remote-command server to the public internet, protected only by the bearer token. Use a long random WINREACH_TOKEN (32+ characters); WinReach warns at startup if the token looks weak.
Quick-tunnel hostnames are random and change every restart. Re-paste the printed URL into your agent, or move to a named Cloudflare tunnel for a stable hostname.
The bearer token is still enforced over the tunnel. Treat the public URL as sensitive and rotate the token after demos.
Auto-install downloads and runs the official cloudflared binary from GitHub releases over HTTPS. If you need a verified/pinned binary, set WINREACH_TUNNEL_AUTOINSTALL=0 and point WINREACH_CLOUDFLARED_PATH at a cloudflared you installed and checked yourself.

Connect Agents

Copy-paste snippets for Claude Code, Claude Desktop, Codex, and Cursor (local stdio and remote HTTP forms) plus the one-click Claude Desktop extension: docs/CONNECT.md.

Full setup guide: Install WinReach and Connect Agents

Feature overview: WinReach Features

Codex ~/.codex/config.toml:

[mcp_servers.winreach]
url = "http://WINDOWS_SERVER_IP:7573/mcp"
bearer_token_env_var = "WINREACH_TOKEN"
tool_timeout_sec = 120
default_tools_approval_mode = "prompt"
enabled = true

Claude Code:

claude mcp add --transport http winreach http://WINDOWS_SERVER_IP:7573/mcp `
  --header "Authorization: Bearer YOUR_TOKEN"

Also see:

Remote Windows Deployment

On the Windows host:

git clone https://github.com/GhouI/winreach-mcp.git
cd winreach-mcp
npm install
$env:WINREACH_TOKEN = "replace-with-a-long-random-token"
$env:WINREACH_HOST = "0.0.0.0"
$env:WINREACH_PORT = "7573"
npm run dev

Open the Windows firewall for the MCP port:

New-NetFirewallRule `
  -DisplayName "WinReach MCP 7573" `
  -Direction Inbound `
  -Protocol TCP `
  -LocalPort 7573 `
  -Action Allow

Restrict your cloud firewall so TCP 7573 is reachable only from trusted IP addresses. If you only need agent access (not raw port access), prefer tunnel mode and keep the bind on 127.0.0.1.

Configuration

Prefer a UI? The setup-web app (Next.js) generates the env vars, a start.ps1, a Windows firewall rule for your allowed IPs, and agent-connect snippets from a form — see setup-web/README.md.

WinReach reads WINREACH_* variables.

Variable	Default	Description
`WINREACH_TOKEN`	required*	Bearer token for a single full-access admin. *Required unless `WINREACH_PRINCIPALS` is set.
`WINREACH_PRINCIPALS`	empty	JSON array of per-user principals: `[{"name","role","token"\|"tokenEnv"\|"tokenHash","allow":[],"deny":[],"tools":[]}]`. Enables per-user authorization. A key may be plaintext (`token`/`tokenEnv`) or a SHA-256 hex `tokenHash` (a presented token authenticates when its SHA-256 matches — so an external store never needs the plaintext). `tools` optionally limits a principal to specific tool names (omit for all).
`WINREACH_COMMAND_ALLOWLIST`	empty	Regex allowlist (comma-separated or JSON array). If non-empty, only matching commands run.
`WINREACH_COMMAND_DENYLIST`	empty	Regex denylist (comma-separated or JSON array). Matching commands are blocked; deny wins over allow.
`WINREACH_AUDIT_LOG`	empty	Path to an append-only JSONL audit log of every tool call.
`WINREACH_TLS_CERT`	empty	PEM certificate path. Set with `WINREACH_TLS_KEY` to serve HTTPS in-app.
`WINREACH_TLS_KEY`	empty	PEM private key path for TLS.
`WINREACH_TLS_KEY_PASSPHRASE`	empty	Passphrase for an encrypted TLS key.
`WINREACH_TLS_CLIENT_CA`	empty	PEM CA bundle to verify client certificates. Enables mutual TLS (requires TLS).
`WINREACH_ALLOW_SCREENSHOT`	`0`	Set to `1` to enable the `take_screenshot` tool. Disabled by default.
`WINREACH_SCREENSHOT_ROLES`	empty	Comma-separated principal roles allowed to capture. Empty means any authenticated principal (when enabled).
`WINREACH_SCREENSHOT_DIR`	temp subdir	Server-owned directory captures are written to. Callers cannot override it.
`WINREACH_SCREENSHOT_RETENTION_HOURS`	`8`	Captures older than this are deleted (on startup and before each capture). Set `0` to keep them indefinitely.
`WINREACH_ALLOW_COMPUTER_USE`	`0`	Set to `1` to enable the `computer_use` desktop-input tool. Disabled by default. GUI control bypasses the command policy, so grant it to trusted roles only.
`WINREACH_COMPUTER_USE_ROLES`	empty	Comma-separated roles allowed to drive the desktop. Empty means any authenticated principal (when enabled).
`WINREACH_COMPUTER_USE_MAX_ACTIONS_PER_SEC`	`10`	Per-principal rate cap on input actions.
`WINREACH_COMPUTER_USE_KEY_DENYLIST`	empty	Comma-separated regexes for key chords to block (e.g. `win\+r`). A speed bump, not a boundary.
`WINREACH_COMPUTER_USE_HALT_FILE`	empty	If this file exists, all `computer_use` actions are refused — an operator kill switch.
`WINREACH_COMPUTER_USE_AUDIT_TEXT`	`0`	Set to `1` to record raw typed text in the audit log. Off by default (length + truncated hash only).
`WINREACH_FILE_ROOT`	empty	Sandbox root for `file_upload`/`file_download`. Setting it enables the tools; all transfer paths resolve within it.
`WINREACH_MAX_FILE_BYTES`	`78643200`	Maximum bytes per transferred file (both directions). Default 75 MB.
`WINREACH_URL`	`http://127.0.0.1:7573/mcp`	Diagnostic client URL for one WinReach server.
`WINREACH_URLS`	empty	Diagnostic client comma-separated URLs for multiple servers using `WINREACH_TOKEN`.
`WINREACH_TARGETS`	empty	Diagnostic client JSON array for named servers and per-target token env vars.
`WINREACH_HOST`	`127.0.0.1`	Bind host. Use `0.0.0.0` only behind a firewall or tunnel.
`WINREACH_PORT`	`7573`	Bind port.
`WINREACH_ENDPOINT_PATH`	`/mcp`	MCP endpoint path.
`WINREACH_ALLOWED_ORIGINS`	empty	Comma-separated allowed `Origin` values.
`WINREACH_SHELL_PATH`	auto	Explicit `pwsh` or `powershell.exe` path.
`WINREACH_CWD`	process cwd	Default working directory.
`WINREACH_TIMEOUT_MS`	`30000`	Default command timeout.
`WINREACH_MAX_OUTPUT_BYTES`	`1048576`	Max captured bytes per output stream.
`WINREACH_TUNNEL`	empty	Set to `cloudflare` to publish the server through a Cloudflare quick tunnel.
`WINREACH_TUNNEL_AUTOINSTALL`	`1`	Auto-download `cloudflared` when missing. Set to `0` to require a preinstalled binary.
`WINREACH_CLOUDFLARED_PATH`	auto	Explicit path to the `cloudflared` binary.

Security

WinReach is a remote command-execution server. Treat it as sensitive infrastructure.

Use a long random WINREACH_TOKEN.
Keep WINREACH_HOST=127.0.0.1 unless you have a trusted network path or are using tunnel mode.
Do not expose WinReach directly to the public internet on a raw port.
Restrict TCP 7573 at your provider firewall.
Tunnel URLs are still protected by the bearer token, but treat them as secrets and rotate after demos.
Run as a dedicated low-privilege Windows user when possible.
Rotate tokens after demos, testing sessions, and shared access.

Hardening

WinReach can now enforce transport security, per-user authorization, command policy, and auditing without an external proxy.

Serve HTTPS in-app (optionally with mutual TLS):

$env:WINREACH_TOKEN = "replace-with-a-long-random-token"
$env:WINREACH_TLS_CERT = "C:\certs\winreach-cert.pem"
$env:WINREACH_TLS_KEY  = "C:\certs\winreach-key.pem"
# Require client certificates (mTLS): connections without a cert signed by this CA
# are dropped during the TLS handshake, before the bearer-token check.
$env:WINREACH_TLS_CLIENT_CA = "C:\certs\client-ca.pem"
npm run dev

Give each client its own identity, role, and command policy:

$env:WINREACH_PRINCIPALS = @'
[
  { "name": "ci",    "role": "admin",    "tokenEnv": "CI_TOKEN" },
  { "name": "agent", "role": "readonly", "tokenEnv": "AGENT_TOKEN",
    "allow": ["^Get-", "^Test-"], "deny": ["Remove-Item", "Stop-Service"],
    "tools": ["powershell_execute"] }
]
'@

Apply a deployment-wide guardrail and record everything:

$env:WINREACH_COMMAND_DENYLIST = "Remove-Item -Recurse,Format-Volume,Stop-Computer"
$env:WINREACH_AUDIT_LOG = "C:\logs\winreach-audit.jsonl"

The global policy plus the caller's principal policy must both allow a command; deny always wins, and a non-empty allowlist blocks anything it does not match. Blocked calls return an MCP error and are written to the audit log.

Install as a Windows service under a dedicated account:

npm run build
$pw = Read-Host -AsSecureString "Service account password"
./scripts/install-service.ps1 -EnvFile .env -ServiceAccount ".\winreach" -ServiceAccountPassword $pw
# Remove later with: ./scripts/uninstall-service.ps1

See SECURITY.md for the full control matrix and what remains out of scope.

Roadmap

Shipped: in-app HTTPS/mTLS, per-client authorization, command allow/deny policy, audit logging, and a Windows service installer (see Hardening).

Still planned:

Named Cloudflare tunnels for stable hostnames
Request-level Windows Integrated Authentication (Negotiate/NTLM)
Rate limiting and per-principal quotas
Git Bash support
Packaged releases