WinHelm — Windows Native MCP Server

WinHelm MCP — The helm for your Windows workspace.
A lightweight, production-grade Windows Native Model Context Protocol (MCP) server featuring a built-in Single-Process Web Gateway (Streamable HTTP /mcp + Server-Sent Events /sse), Real-Time Web Monitor Dashboard, 38 System Tools with Dynamic Profile Loading, and MCP File Preview Resource.

📖 Tools Reference • ⚙️ Tool Profiles • 🛡️ Security Architecture • 💡 Agent Examples • 📝 Changelog • 🤝 Contributing

Table of Contents

• Overview

• Key Features

• System Requirements

• Architecture & Live Dashboard

• Quick Start

• Tool Profiles ("Load Only What You Need")

• Client Configuration

  • Claude Desktop

  • Cursor IDE

  • ChatGPT & OpenAI MCP Tunnel

  • Remote & Tailscale Connection

• Tools Overview (38 Tools)

• MCP Resources & Web Endpoints

• Configuration & Environment Variables

• Standalone Executable (winhelm.exe)

• Documentation & Deep Dive

• License

Overview

WinHelm bridges the gap between AI assistants (Claude, Cursor, LibreChat, ChatGPT) and the Windows operating system. Unlike generic cross-platform servers, WinHelm is built from the ground up for Windows with:

• Zero Gateway Overhead: Native single-process Web Gateway supporting both modern Streamable HTTP (/mcp) and standard Server-Sent Events (/sse). No external proxy (supergateway or reverse proxy) required.

• Safety First: Accidental deletions go to the Windows Recycle Bin instead of permanent destruction. Dangerous commands (format-volume, rmdir /s /q c:\) are strictly blocked by default.

• First-class Windows Integrations: NVIDIA/WMI GPU telemetry, Windows Services management, native UTF-8 PowerShell runner, and headless Microsoft Edge PDF compilation.

Key Features

1. All-in-One Gateway & Web Monitor:

   • Streamable HTTP: http://<HOST>:8788/mcp (Modern MCP standard)

   • SSE Stream & POST: http://<HOST>:8788/sse and /message

   • Web Monitor Dashboard: http://<HOST>:8788/ (Interactive metrics, sessions, drives, memory, GPU, and live audit logs)

   • Interactive File Viewer: http://<HOST>:8788/preview?path=... (Rich Markdown & code viewer with syntax formatting)

   • Health Check: http://<HOST>:8788/health

2. High-Observability Logging & Secret Masking:

   • Microsecond execution timings with ANSI color-coded tags ([HTTP], [TOOL-START], [TOOL-DONE], [SECURITY]).

   • Automatically sanitizes Bearer tokens, API keys (sk-***, ghp_***), AWS credentials (AKIA***), JSON properties ("authToken", "password", "x-api-key"), and sensitive arguments before printing or writing logs.

3. Background Daemon Task Engine:

   • Execute long-running dev servers (npm run dev, docker compose up) as background tasks with detached PIDs, non-blocking logs streaming, and interactive stdin support.

4. High-Performance Code Search (Ripgrep):

   • Integrates ripgrep (rg.exe) for fast regex search with streaming pagination (page, pageSize, hasMore) to prevent context window overflow.

5. Headless PDF Generation:

   • Converts Markdown and HTML into clean PDF documents using pre-installed Microsoft Edge or Chrome without requiring heavy dependencies like Puppeteer.

6. Tailscale & Remote Ready:

   • Optionally bind to 0.0.0.0 or your Tailscale IP (100.x.y.z) for cross-device access. Default is 127.0.0.1 (loopback-only). Non-loopback binding requires Bearer Token verification and is guarded by a startup safety gate.

System Requirements

Architecture & Dashboard

System Architecture

flowchart TD
    Client["AI Client (Claude / Cursor / Remote)"]

    subgraph WinHelm["WinHelm Server (Port 8788)"]
        subgraph Gateway["Single-Process Unified Gateway"]
            MCP_HTTP["Streamable HTTP (/mcp)"]
            MCP_SSE["SSE Gateway (/sse, /message)"]
            Dashboard["Web Monitor (/ & /dashboard)"]
            PreviewUI["File Preview (/preview)"]
            Health["Health & Audit Export (/health, /api/monitor/*)"]
        end

        subgraph Security["Security & Governance"]
            AuthGuard["Bearer Token Authentication"]
            RateLimit["Rate Limiter (120 req/min)"]
            PathGuard["Allowed Directories Guard"]
            CmdGuard["Blocked Commands Guard"]
            Sanitizer["Secret Masking (API Keys / Passwords)"]
        end

        subgraph Engines["Core Engine Layer"]
            PSEngine["PowerShell UTF-8 Runner"]
            TaskEngine["Background Daemon Task Engine"]
            FSEngine["Filesystem & Safe Delete (Recycle Bin)"]
            SearchEngine["Ripgrep Streaming Engine"]
            PDFEngine["Edge / Chrome Headless PDF Engine"]
            SysEngine["System, GPU & Windows Services Inspector"]
        end
    end

    subgraph Windows["Windows Operating System"]
        Win32["Win32 Shell / Recycle Bin"]
        PowerShell["PowerShell CLI / Tasks"]
        WMI_NVIDIA["WMI & nvidia-smi Telemetry"]
        SCM["Windows Service Control Manager"]
    end

    Client <--> Gateway
    Gateway --> Security
    Security --> Engines
    Engines <--> Windows

Web Monitor & Live Dashboard

Access the built-in real-time dashboard in your browser at http://localhost:8788/:

Live Task Execution & Telemetry Streaming

Interactive File & Markdown Preview (preview://file)

Access syntax-highlighted code and rendered Markdown directly at http://localhost:8788/preview?path=<filepath>:

Quick Start

1. Installation & Setup

Option A: Standalone Executable (Recommended for Production)

Download the portable zero-dependency winhelm.exe from GitHub Releases or compile locally with npm run build:exe. Requires no Node.js runtime on Windows 10/11.

Option B: NPM CLI (Convenient for Dev & Testing)

# Install globally
npm install -g winhelm-mcp

# Run immediately
winhelm --profile dev

# Or run on-demand with npx (no global install required)
npx winhelm-mcp --profile dev

Option C: Clone & Build from Source

git clone https://github.com/dhammawatthumpra-coder/winhelm-mcp.git
cd winhelm-mcp
npm install
npm run build

2. Start the Server

# Start standard server on port 8788 (full profile)
npm start

# Or start with a lightweight profile for coding agents (dev) or small models (minimal)
node dist/index.js --profile dev

# Or customize port and bearer token via CLI flags
node dist/index.js --port 8788 --auth my-secret-token

# Or run in Read-Only mode (disallows file edits, deletions, and killing processes)
node dist/index.js --read-only

3. Verify Health Check

Visit http://localhost:8788/health in your browser. You should receive:

{
  "status": "ok",
  "server": "winhelm-mcp",
  "version": "1.1.0",
  "activeSessions": {
    "sse": 0,
    "streamableHttp": 0
  },
  "uptimeSeconds": 12,
  "timestamp": "2026-09-28T08:00:00.000Z"
}

Tool Profiles ("Load Only What You Need")

AI coding assistants perform much better when their context window isn't bloated with dozens of unneeded tool schemas. WinHelm implements a Dynamic Profile System so your agent sees only the tools it actually needs:

# 1. Minimal Profile: 6 essential tools for small models (Haiku, Llama 8B, local LLMs)
winhelm --profile minimal

# 2. Core Profile: 15 essential tools (terminal, file read/write/edit/search/hash, process list, telemetry)
winhelm --profile core

# 3. Developer Profile: 28 tools (Core + background tasks, ripgrep, zip archives, HTTP requests, PDF reports, system open & file preview)
winhelm --profile dev

# 4. SysAdmin Profile: 37 tools (All Core + tasks, ripgrep, archives, services, event logs, network, process kill, desktop automation & preview — all except pdf_generate)
winhelm --profile sysadmin

# 5. Full Suite: All 38 tools + interactive preview resource (default)
winhelm --profile full

Profile Inclusions

Token Economics & Model Optimization

Pro Tip: In claude_desktop_config.json, pass ["--profile", "dev"] under args for software development, or ["--profile", "minimal"] for Claude Haiku!

Client Configuration

1. Claude Desktop (claude_desktop_config.json)

Path: %APPDATA%\Claude\claude_desktop_config.json

Option A: Zero-Install via npx (Easiest & Recommended)

{
  "mcpServers": {
    "winhelm": {
      "command": "npx",
      "args": ["-y", "winhelm-mcp", "--stdio", "--profile", "dev"],
      "env": {
        "MCP_ALLOWED_DIRECTORIES": "D:\\Workspace,C:\\Projects"
      }
    }
  }
}

Instant Setup: Runs the latest official winhelm-mcp directly from npm on demand without manual cloning or global installation. Specify permitted workspace paths in MCP_ALLOWED_DIRECTORIES.

Option B: Remote / Local SSE Gateway

{
  "mcpServers": {
    "winhelm": {
      "url": "http://127.0.0.1:8788/sse",
      "headers": {
        "Authorization": "Bearer my-secret-token"
      }
    }
  }
}

Option C: Direct Stdio / Node Process (From Source)

{
  "mcpServers": {
    "winhelm": {
      "command": "node",
      "args": ["<PATH_TO_WINHELM>/dist/index.js", "--stdio", "--profile", "dev"],
      "env": {
        "MCP_ALLOWED_DIRECTORIES": "D:\\mcp,C:\\Projects"
      }
    }
  }
}

Context Optimization: Supplying "--profile", "dev" restricts tools to 28 developer essentials, saving ~32% context tokens while preserving all coding, ripgrep, background task, PDF, archive, and preview capabilities.

Option D: Standalone Executable (winhelm.exe)

{
  "mcpServers": {
    "winhelm": {
      "command": "<PATH_TO_WINHELM>\\dist\\winhelm.exe",
      "args": ["--stdio", "--profile", "dev"]
    }
  }
}

Option E: Per-Project Dedicated Config File (Isolated Profiles & Roots)

{
  "mcpServers": {
    "winhelm-project-a": {
      "command": "winhelm",
      "args": ["--stdio", "--config", "D:\\mcp\\configs\\project-a.json"]
    }
  }
}

Multi-Instance Isolation: Each project config file maintains its own isolated allowedDirectories, profile, and security rules without modifying the shared default winhelm.config.json. CLI overrides are session-only (--no-persist by default) to prevent instances from colliding.

2. Cursor IDE

In Cursor Settings (Settings -> Features -> MCP -> Add new MCP server):

• Name: winhelm

• Type: sse

• URL: http://127.0.0.1:8788/sse

(If authentication is configured, add "Authorization": "Bearer <YOUR_TOKEN>" to the headers section).

3. ChatGPT & OpenAI MCP Tunnel (tunnel-client)

WinHelm integrates seamlessly with OpenAI's official tunnel-client daemon, allowing ChatGPT to execute Windows commands, inspect files, and manage background tasks directly over a secure Cloudflare Tunnel:

Profile Configuration (winhelm-mcp.yaml)

config_version: 1

control_plane:
  base_url: "https://api.openai.com"
  tunnel_id: "your-tunnel-id-here"
  api_key: "env:CONTROL_PLANE_API_KEY"

health:
  listen_addr: "127.0.0.1:18026"

admin_ui:
  open_browser: false

log:
  level: info
  format: json

mcp:
  commands:
    # Direct stdio connection with dev profile (~32% token savings for ChatGPT)
    - channel: main
      command: 'node D:/mcp/winhelm-mcp/dist/index.js --stdio --profile dev'

Running the Tunnel

.\tunnel-client.exe run --profile-file winhelm-mcp.yaml

Purity Guard: In --stdio mode, WinHelm routes all operational logs to stderr, leaving stdout purely for JSON-RPC messages to guarantee zero parsing errors on ChatGPT.

4. Remote & Tailscale Connection

WinHelm binds by default to 127.0.0.1 (localhost only). To allow secure cross-device access over private networks like Tailscale or WireGuard, bind to 0.0.0.0 or your Tailscale IP:

1. Retrieve your machine's Tailscale IP (e.g. 100.80.20.10) or Tailscale Funnel domain (e.g. https://your-node.ts.net).

2. Start WinHelm with --host 0.0.0.0 and a strong authentication token:

   node dist/index.js --port 8788 --host 0.0.0.0 --auth super-secure-token-here

   ⚠️ Host Safety Gate: Binding to --host 0.0.0.0 exposes the server to your local network and Tailscale. You must supply an authentication token (--auth), otherwise startup will be rejected with exit code 1 by the host safety gate.

3. Connect your mobile or remote Claude / Cursor / ChatGPT client:

   • Streamable HTTP: http://100.80.20.10:8788/mcp

   • SSE Stream: http://100.80.20.10:8788/sse

   • Web Monitor Dashboard: http://100.80.20.10:8788/?token=super-secure-token-here (or Tailscale Funnel URL)

   • Header: Authorization: Bearer super-secure-token-here

Claude.ai Custom Connectors (URL Query Token)

Claude.ai Custom Connectors and certain web/mobile clients do not provide a UI field to enter custom HTTP headers (such as Authorization: Bearer <token>). WinHelm natively supports passing the authentication token directly via the URL query parameter:

• Server URL: https://<your-tailnet-domain>.ts.net/mcp?token=<YOUR_AUTH_TOKEN>

• Authentication: Select No sign-in

• Transport (under Advanced): Streamable HTTP (Default)

🔒 Security Guarantee: Passing the token in the URL query parameter still triggers full timing-safe cryptographic verification on the server, ensuring your Windows machine remains completely protected from unauthorized internet access without needing a complex OAuth setup.

Tools Overview (38 Tools)

WinHelm provides 38 focused Windows native tools grouped across 6 functional categories. Each tool is loaded dynamically based on your active --profile:

📖 See docs/TOOLS.md for full parameter specifications, types, returns, and schemas.

MCP Resources & Web Endpoints

MCP Resources

WinHelm exposes 1 dedicated Model Context Protocol resource:

Gateway Web Endpoints

WinHelm hosts a full web application on a single port (default: 8788):

• / & /dashboard — Real-time Web Monitor Dashboard (CPU, RAM, GPU, sessions, requests, live logs).

• /mcp — Streamable HTTP transport endpoint.

• /sse — Server-Sent Events transport endpoint for clients like Claude Desktop and Cursor.

• /message — POST endpoint for incoming JSON-RPC messages in SSE mode.

• /preview — Interactive browser file viewer (/preview?path=D:\project\README.md).

• /health — JSON health status and server uptime probe.

• /api/monitor/stats — JSON hardware and session statistics.

• /api/monitor/export?format=json|csv — Audit log export for security compliance.

💡 Browser Dashboard Access with Authentication:
When authentication is enabled (--auth <token> or authToken), accessing the Web Monitor Dashboard or Previewer via your browser requires passing the token once in the URL:

• Dashboard: http://<HOST>:8788/?token=<YOUR_AUTH_TOKEN> (or https://<your-tailnet-domain>.ts.net/?token=<YOUR_AUTH_TOKEN>)

• File Preview: http://<HOST>:8788/preview?path=D:\project\README.md&token=<YOUR_AUTH_TOKEN>
  WinHelm validates the token, displays live metrics and real-time logs, and sets a secure HttpOnly session cookie so subsequent dashboard navigation stays authenticated without re-entering the token.

Configuration & Environment Variables

WinHelm loads configuration in the following order of precedence:

1. CLI Flags

2. Environment Variables

3. winhelm.config.json

4. Default settings

Reference Table

winhelm.config.json

Create or modify winhelm.config.json in your project root or %USERPROFILE%\.winhelm\config.json:

{
  "blockedCommands": [
    "format-volume",
    "format-disk",
    "clear-disk",
    "stop-computer",
    "restart-computer",
    "rmdir /s /q c:\\",
    "del /f /s /q c:\\"
  ],
  "allowedDirectories": ["D:\\mcp", "C:\\Workspace"],
  "allowSystemExecution": true,
  "profile": "dev",
  "fileReadLineLimit": 2000,
  "defaultTimeoutMs": 60000,
  "telemetryEnabled": false,
  "authToken": null,
  "readOnly": false,
  "rateLimitWindowMs": 60000,
  "rateLimitMaxRequests": 120
}

Security Boundaries vs. Defense-in-Depth:

• True Security Boundaries: Authentication Token (authToken), Tool Profiles (minimal, core), and Read-Only Mode (readOnly). For untrusted or public environments, configure an authToken and use --profile core to exclude terminal execution completely.

• Defense-in-Depth: The command blocklist protects against accidental destructive commands (format-volume, rmdir /s /q c:\), but is not an impenetrable sandbox. allowedDirectories strictly bounds native File Tools (file_read, file_write, create_zip, etc.) and default CWD.

• DNS Rebinding Defense: WinHelm validates Host headers against an allowlist (localhost, 127.0.0.1, [::1], *.ts.net). Requests from unauthorized hostnames are rejected with HTTP 403 Forbidden.

• Remote Tunnel Fail-Closed Gate: Requests arriving through a reverse proxy or tunnel without an authToken configured are rejected immediately with HTTP 403 Forbidden.

• Fail-Closed Filesystem: allowedDirectories: [] blocks all filesystem operations by default. Specify target paths (e.g. ["D:\\mcp", "C:\\Workspace"]). Wildcard ["*"] is strictly discouraged for unauthenticated or public network exposures.

Windows Background Service (Always-On Daemon)

WinHelm includes a built-in service manager using Windows Task Scheduler to run reliably in the background across system reboots:

# Install as a persistent Windows Service (Run PowerShell as Administrator)
npm run service:install

# Check service status
npm run service:status

# Stop / Start the service
npm run service:stop
npm run service:start

# Uninstall the service
npm run service:uninstall

Standalone Single-File Executable (winhelm.exe)

You can compile WinHelm into a standalone .exe (~2.6 MB) that requires no Node.js installation on target machines:

npm run build:exe

The resulting executable will be generated at dist/winhelm.exe:

# Run standalone executable with custom port
.\dist\winhelm.exe --port 9000 --auth my-token

Security, Rate Limiting & Auditing

1. Automatic Secret Redaction:

   • Automatically sanitizes sensitive keys (sk-..., ghp_..., Bearer ********, and password values) from terminal output, dashboard UI, and log files.

2. Built-in Rate Limiting (Sliding Window):

   • Enforces a sliding window ceiling of 120 requests per minute per IP address, preventing runaway client loops.

3. Auditing & Log Rotation:

   • Logs are stored in logs/winhelm-YYYY-MM-DD.log (capped at 10 MB per file, auto-pruning logs older than 7 days).

   • Export audit logs anytime via browser or API:

     • http://localhost:8788/api/monitor/export?format=json

     • http://localhost:8788/api/monitor/export?format=csv

4. Fail-Closed Filesystem Confinement:

   • allowedDirectories: [] blocks all filesystem operations by default for safety.

   • Symlinks and NTFS directory junctions are resolved via fs.realpathSync before boundary evaluation.

5. Loopback-First Network Binding:

   • Default host is 127.0.0.1 (loopback only).

   • Non-loopback binding (such as 0.0.0.0) without --auth is blocked at startup with exit code 1.

   • Bearer tokens are compared using crypto.timingSafeEqual with buffer length validation to prevent timing side-channels.

Troubleshooting

1. Port Conflict (EADDRINUSE: address already in use :::8788)

• Cause: Another process or previous instance is using port 8788.

• Solution: Specify a different port using --port:

  node dist/index.js --port 8790

  Or check which process is holding port 8788:

  Get-NetTCPConnection -LocalPort 8788 | Select-Object OwningProcess

2. HTTP 401 Unauthorized

• Cause: WinHelm was started with --auth <token> or MCP_AUTH_TOKEN, but the MCP client didn't supply matching credentials.

• Solution 1 (Clients with Custom Header Support): Add the Bearer token header to your client configuration:

  "headers": {
    "Authorization": "Bearer <YOUR_TOKEN>"
  }

• Solution 2 (Claude.ai Custom Connectors without Header UI): Append the token directly to the Server URL and select No sign-in:

  https://<your-domain>/mcp?token=<YOUR_TOKEN>

• Solution 3 (Browser Dashboard & File Preview): Append ?token=<YOUR_TOKEN> to the URL in your browser:

  https://<your-domain>/?token=<YOUR_TOKEN>
  https://<your-domain>/preview?path=...&token=<YOUR_TOKEN>

3. PowerShell Execution Policy Restriction

• Cause: Windows blocks script execution (File cannot be loaded because running scripts is disabled on this system).

• Solution: Run with bypass flag:

  Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

4. Windows Service Installation Error (Access is denied)

• Cause: npm run service:install registers a task in Windows Task Scheduler, which requires elevated privileges.

• Solution: Open PowerShell as Administrator and re-run npm run service:install.

5. Tailscale / Remote Timeout

• Cause: Windows Defender Firewall is blocking inbound connections on port 8788.

• Solution: Allow port 8788 in Windows Firewall:

  New-NetFirewallRule -DisplayName "WinHelm MCP Gateway" -Direction Inbound -LocalPort 8788 -Protocol TCP -Action Allow

6. PDF Generation Headless Browser Not Found

• Cause: Neither Microsoft Edge nor Google Chrome could be located in default system paths.

• Solution: Ensure Microsoft Edge is installed at its standard location (C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe) or install Google Chrome.

7. Host Safety Gate Blocks Startup (Non-loopback binding requires --auth)

• Cause: You attempted to bind to a non-loopback address (such as 0.0.0.0) without specifying an authentication token.

• Solution: Add --auth <token> or set the MCP_AUTH_TOKEN environment variable. This security gate prevents accidental public exposure of your host system without authentication.

Documentation & Deep Dive

For in-depth guides, architectural references, and developer guidelines, explore the docs/ folder:

• 📖 Comprehensive Tools Reference: Exhaustive documentation for all 38 tools, including parameter types, options, return formats, and JSON-RPC examples.

• ⚙️ Tool Profiles & Context Optimization: Deep dive into the 5 built-in profiles (minimal, core, dev, sysadmin, full), custom --tools filtering, token economics, and LLM optimization recipes.

• 🛡️ Security Model & Architecture: Deep dive into the 5-layer security model, path confinement, regex command blacklists, and secret masking.

• 💡 Real-World Agent Examples: End-to-end workflows showing how AI agents build projects, troubleshoot Windows crashes, and generate executive PDFs.

• 📝 Changelog: Release notes and version history following Keep a Changelog.

• 🤝 Contributing Guide: Instructions for developing, running tests, and opening Pull Requests.

License

This project is licensed under the MIT License — see the LICENSE file for details.
Built cleanly from the ground up for the Windows Model Context Protocol developer community.