Winreach Mcp

WinReach MCP

[](https://github.com/GhouI/winreach-mcp/actions/workflows/ci.yml) [](LICENSE) [](https://modelcontextprotocol.io) [](https://learn.microsoft.com/powershell/)

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

[](assets/winreach-demo.mp4)

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](assets/winreach-demo.mp4) · built with Remotion (source and re-render steps in [video/](video/README.md)).

There's also a vertical 4:5 LinkedIn cut with burned-in captions — [assets/winreach-linkedin.mp4](assets/winreach-linkedin.mp4) (cover: [assets/winreach-linkedin-cover.png](assets/winreach-linkedin-cover.png), captions: [assets/winreach-linkedin.srt](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](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 "
...

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](docs/CONNECT.md).

Full setup guide: [Install WinReach and Connect Agents](docs/INSTALLANDAGENT_USAGE.md)

Feature overview: [WinReach Features](docs/FEATURES.md)

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:

• [Codex config example](examples/codex-config.toml)
• [Claude Code MCP JSON example](examples/claude.mcp.json)

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](#public-access-with-one-command) and keep the bind on 127.0.0.1.

Configuration

Prefer a UI? The [setup-web](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](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 c

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: GhouI
• Source: GhouI/winreach-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.