luxeave/winbridge-mcp

WinBridge MCP

Read‑only Windows system bridge that exposes a set of safe inspection tools over the Model Context Protocol (MCP) via an HTTP server. Designed for vulnerability assessment and inventory on Windows Server/Workstation without making changes to the host.

• Protocol: MCP 2024‑11‑05
• Transport: HTTP (Server‑Sent Events; stateful sessions)
• Port/Path: 0.0.0.0:3000/mcp
• Safety: Tools are read‑only; registry access restricted to safe roots

How it works (high‑level)

• The server is a Rust binary using:
  • tokio for async runtime
  • axum web framework
  • rmcp (MCP Rust SDK) with the streamable HTTP transport
  • tracing for structured logging
• At runtime, each request session gets a fresh WinBridge tool handler.
• Tools shell out to PowerShell to gather data, return JSON back to the MCP client.
• The HTTP service is mounted at /mcp and keeps connections alive for streaming.

Prerequisites

• Windows host (recommended: Windows Server 2019/2022 or Windows 10/11)
• PowerShell available as powershell.exe (Windows PowerShell 5.x)
• Rust toolchain (latest stable recommended)
• Network access to TCP 3000 from your MCP client (or run locally)

Note: This server binds to 0.0.0.0:3000 by default and does not implement authentication. Place it behind a firewall, restrict to private networks, or front with a reverse proxy that terminates TLS and enforces auth.

Build

1. Install Rust (https://rustup.rs/)

2. In the repo root, build the binary:

   # Debug build
   cargo build
   
   # Release build
   cargo build --release
   

The output binary will be at target\debug\winbridge-mcp.exe or target\release\winbridge-mcp.exe.

Run (local)

1. Optionally enable logs:

   $env:RUST_LOG = "info"   # or trace, debug, warn, error
   

2. Start the server:

   .\target\release\winbridge-mcp.exe
   

3. Ensure the port is reachable (from the host):

   Test-NetConnection -ComputerName localhost -Port 3000
   

4. Point your MCP HTTP client at http://<host>:3000/mcp.

Changing the port/address: edit the bind in src/main.rs (0.0.0.0:3000) and rebuild. There is no env var for the port at this time.

Deploy as a Windows Service (two options)

Option A: Built‑in Service Control Manager (SC)

# Install the service
sc.exe create WinBridgeMCP binPath= "C:\path\to\winbridge-mcp.exe" start= auto DisplayName= "WinBridge MCP"

# Start it
sc.exe start WinBridgeMCP

# Check status
sc.exe query WinBridgeMCP

# Remove service (when needed)
sc.exe delete WinBridgeMCP

• Ensure a firewall rule allows inbound TCP 3000 from your client/network:

  New-NetFirewallRule -DisplayName "WinBridge MCP" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 3000
  

Option B: NSSM (Non‑Sucking Service Manager)

nssm install WinBridgeMCP "C:\path\to\winbridge-mcp.exe"
nssm set WinBridgeMCP Start SERVICE_AUTO_START
nssm start WinBridgeMCP

Using with an MCP client

• This server speaks MCP over HTTP with streaming. Configure your MCP client to connect to:
  • URL: http://<host>:3000/mcp
• Exact client configuration depends on the client implementation. Some tools expect stdio transport (not HTTP); use an MCP client that supports HTTP/SSE transports.

Tools exposed (read‑only)

Each tool returns JSON. Parameter objects are shown with defaults.

• os_info

  • Description: OS caption, version, build, arch, hostname, last boot, uptime (hours)
  • Params: {}

• local_users

  • Description: List local users (Name, Enabled, LastLogon)
  • Params: { only_enabled?: bool }

• local_groups

  • Description: List local groups; optionally include members
  • Params: { include_members?: bool = true }

• installed_programs

  • Description: Registry‑based software inventory (DisplayName, Version, Publisher, InstallDate)
  • Params: { name_contains?: string, limit?: number = 200 }

• services

  • Description: Windows services (Name, DisplayName, State, StartMode, StartName, PathName)
  • Params: { state?: string, start_mode?: string, limit?: number = 500 }

• firewall_rules

  • Description: Windows Firewall rules (DisplayName, Enabled, Direction, Action, Profile)
  • Params: { direction?: string, only_enabled?: bool = true, limit?: number = 500 }

• scheduled_tasks

  • Description: Scheduled tasks with last/next run times
  • Params: { state?: string, limit?: number = 500 }

• shares

  • Description: SMB shares (Name, Path, Description, FolderEnumerationMode, EncryptData)
  • Params: {}

• network_config

  • Description: Per‑adapter IPv4/IPv6 and DNS servers
  • Params: {}

• hotfixes

  • Description: Installed hotfixes (KBs)
  • Params: {}

• open_ports

  • Description: Listening TCP ports and owning process
  • Params: { limit?: number = 500 }

• event_log_recent

  • Description: Recent events from a Windows event log with optional level filter
  • Params: { log_name?: string = "System", level?: string, max_events?: number = 200 }

• read_registry_key

  • Description: Read a registry key; restricted to HKLM:\SOFTWARE, HKLM:\SYSTEM, HKCU:\Software
  • Params: { path: string, names?: string[] }

Logging

• Controlled via RUST_LOG (e.g., info, debug, trace).
• Logs are emitted to stdout/stderr by default. When running as a service, consider redirecting output or using a service wrapper that captures logs.

Security and limitations

• Read‑only by design; tools do not change system state.
• Registry reads are restricted to safe roots and sanitized for basic injection resistance.
• No authentication or TLS is implemented by this server:
  • Restrict network access (firewall, private networks)
  • Optionally front with a reverse proxy that enforces mTLS/OIDC and TLS termination
• Runs only on Windows (uses powershell.exe). Linux/macOS are not supported without code changes.

Development tips

• Set logs: set RUST_LOG=debug (cmd) or $env:RUST_LOG='debug' (PowerShell)

• Run fast dev loop:

  cargo run
  

• Lint/format (if you have tools installed):

  cargo fmt
  cargo clippy --all-targets --all-features -D warnings
  

Troubleshooting

• Port already in use: choose another port (edit src/main.rs) or stop the conflicting service.
• No data returned / errors:
  • Ensure the process has permission to run PowerShell and query CIM/WMI
  • Run the server elevated if your environment restricts these operations
  • Check RUST_LOG=debug for more detail
• Client cannot connect:
  • Verify firewall and that Test-NetConnection -Port 3000 succeeds
  • Ensure your client supports MCP over HTTP/SSE

License

Proprietary (or fill in your license).