WinBridgeAgent

WinBridgeAgent

      

中文文档

WinBridgeAgent is an open-source Windows local capability service that implements the Model Context Protocol (MCP) standard, providing traceable Windows system operations for AI assistants such as Claude Desktop, OpenAI, etc.

WinBridgeAgent Pro (Free Download)

In addition to the open-source edition, WinBridgeAgent Pro is now available as a free download.

The Pro edition is designed for users who need a more complete Windows Agent/Node experience, with ongoing improvements toward a more production-ready Windows node (closer to the OpenClaw Node experience).

Key enhancement areas (ongoing) include:

• Stronger media capabilities: camera photo/video capture and screen recording
• Deeper system integration: notifications, location, audio, and related OS features
• More powerful automation: expanded shell command execution with permission/safety controls
• Better production readiness: timeout handling, resource cleanup, error handling, and stability work

See details and download here:

• https://codyard.dev/winbridgeagentpro

Architecture

+------------------------------------------------------+
|                Local Area Network (LAN)              |
|                                                      |
|   +--------------------+                             |
|   |   MCP Client       |                             |
|   | (OpenClaw / Agent) |                             |
|   |  - LLM reasoning   |                             |
|   |  - Tool planning   |                             |
|   +---------+----------+                             |
|             | MCP Protocol (HTTP/SSE)                |
|             |                                        |
|   +---------v------------------------------------+   |
|   |           Windows PC                          |   |
|   |                                              |   |
|   |   +--------------------------------------+   |   |
|   |   |  WinBridgeAgent                      |   |   |
|   |   |  (Local Tray MCP Server)             |   |   |
|   |   |                                      |   |   |
|   |   |  - MCP Server (localhost / LAN)      |   |   |
|   |   |  - Policy & Permission Guard         |   |   |
|   |   |  - Tool Execution Layer              |   |   |
|   |   |  - Audit & Logging                   |   |   |
|   |   +-----------+--------------------------+   |   |
|   |               |                              |   |
|   |      +--------v--------+                     |   |
|   |      | Windows System  |                     |   |
|   |      | APIs / Resources|                     |   |
|   |      | (FS / Screen /  |                     |   |
|   |      |  Clipboard /    |                     |   |
|   |      |  Process etc.)  |                     |   |
|   |      +-----------------+                     |   |
|   |                                              |   |
|   +----------------------------------------------+   |
|                                                      |
+------------------------------------------------------+

Optional External Dependencies:
- GitHub Releases (Auto Update)
- Optional Remote Services (APIs, Cloud tools)

Features

Core

• MCP Protocol: Full Model Context Protocol implementation
• UTF-8 Compatibility: MCP tool outputs are UTF-8 encoded, including non-ASCII Windows paths
• HTTP API: HTTP interface for remote control
• Real-time Monitoring: Dashboard window with live request/response display
• Audit Logging: Complete operation logging
• System Tray: Convenient graphical management interface
• Flexible Configuration: Switch between 0.0.0.0 and 127.0.0.1 listen address
• Auto Update: Automatic GitHub release checking with one-click download

File & System Operations

• File Reading: Disk enumeration, directory listing, file reading (line ranges), content search
• File Operations: Delete, copy, move, create directories
• Clipboard: Read/write clipboard content via HTTP API (text, images, files)
• Screenshots:
• Full screen (HTTP API, PNG/JPEG)
• Window capture (MCP tool, by window title)
• Region capture (MCP tool, by coordinates)

Process & Window Management

• Window Management: List all open windows with details
• Process Queries: List all running processes with details
• Process Management: Terminate processes, adjust priority (with protected process blocklist)
• Command Execution: Execute system commands and capture output

Power Management

• Shutdown: Delayed, forced, with custom message
• Restart: Delayed, forced
• Hibernate & Sleep: System hibernate and sleep
• Cancel Shutdown: Cancel scheduled shutdown/restart

Auto Update

• Version Check: Automatic GitHub release checking
• Update Notification: Friendly notification dialog
• One-click Download: Open GitHub Release page
• Multi-channel: Stable and Beta channels
• Multi-language: Simplified Chinese, English

System Requirements

• Windows 10/11 (x64, x86, ARM64)
• No additional runtime dependencies

Quick Start

Install from MCP Registry

WinBridgeAgent is published on the MCP Registry as io.github.codyard/winbridgeagent. MCP clients that support the registry can install it directly.

Manual Install

1. Download the latest release from GitHub Releases
2. Run WinBridgeAgent-x64.exe (64-bit) or WinBridgeAgent-x86.exe (32-bit)
3. The program appears in the system tray
4. Configure your MCP client (see below)

For OpenClaw + Windows node setup, see windows-node-install.en.md.

MCP Client Configuration

WinBridgeAgent works with any MCP-compatible client. Below are setup instructions for popular clients.

Note: Replace <windows-ip> with the IP address of the Windows PC running WinBridgeAgent (e.g. 192.168.1.100). Use localhost only if the MCP client runs on the same Windows machine.

Claude Desktop

Edit claude_desktop_config.json:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
    "mcpServers": {
        "winbridgeagent": {
            "url": "http://<windows-ip>:35182",
            "transport": "http"
        }
    }
}

Cursor

1. Open Settings → MCP
2. Click Add new MCP server
3. Fill in:

• Name: winbridgeagent
• Type: http
• URL: http://<windows-ip>:35182

Or edit .cursor/mcp.json in your project root:

{
    "mcpServers": {
        "winbridgeagent": {
            "url": "http://<windows-ip>:35182",
            "transport": "http"
        }
    }
}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
    "mcpServers": {
        "winbridgeagent": {
            "serverUrl": "http://<windows-ip>:35182"
        }
    }
}

OpenClaw

1. Open Settings → MCP Servers
2. Click Add
3. Set:

• Name: winbridgeagent
• Transport: HTTP
• URL: http://<windows-ip>:35182

For a step-by-step Windows node deployment walkthrough (including mcporter pairing), see windows-node-install.en.md.

Cherry Studio

1. Open Settings → MCP Servers
2. Click Add Server
3. Select Streamable HTTP type
4. Set URL to http://<windows-ip>:35182

Cline (VS Code)

Edit cline_mcp_settings.json in your VS Code settings:

{
    "mcpServers": {
        "winbridgeagent": {
            "url": "http://<windows-ip>:35182",
            "transportType": "http"
        }
    }
}

Generic MCP Client

Any MCP client that supports HTTP transport can connect using:

• Server URL: http://<windows-ip>:35182
• Transport: HTTP (Streamable HTTP)
• Protocol Version: 2024-11-05

HTTP API

The server listens on the configured port (default 35182).

Open-source edition: No Bearer Token authentication required. All API endpoints are directly accessible.

Endpoints

| Method | Path | Description | |--------|------|-------------| | GET | / | API endpoint list | | GET | /health | Health check | | GET | /status | Server status and info | | GET | /disks | List all disk drives | | GET | /list?path=<path> | List directory contents | | GET | /read?path=<path> | Read file content | | GET | /search?path=<path>&query=<q> | Search file content | | GET | /clipboard | Read clipboard | | PUT | /clipboard | Write clipboard | | GET | /screenshot | Take screenshot | | GET | /windows | List all windows | | GET | /processes | List all processes | | POST | /execute | Execute command | | GET | /exit | Shutdown server | | POST | /mcp/initialize | MCP initialize | | POST | /mcp/tools/list | MCP list tools | | POST | /mcp/tools/call | MCP call tool |

Examples

Replace <windows-ip> below with the actual IP of your Windows PC (or use localhost if testing on the same machine).

# Server status
curl http://<windows-ip>:35182/health

# List disks
curl http://<windows-ip>:35182/disks

# List directory
curl "http://<windows-ip>:35182/list?path=C:\\"

# Read file
curl "http://<windows-ip>:35182/read?path=C:\\test.txt"

# Search file content
curl "http://<windows-ip>:35182/search?path=C:\\test.txt&query=keyword"

# Read clipboard
curl http://<windows-ip>:35182/clipboard

# Write clipboard
curl -X PUT -H "Content-Type: application/json" \
  -d '{"content":"Hello World"}' http://<windows-ip>:35182/clipboard

# Take screenshot
curl http://<windows-ip>:35182/screenshot

# List windows
curl http://<windows-ip>:35182/windows

# List processes
curl http://<windows-ip>:35182/processes

# Execute command
curl -X POST -H "Content-Type: application/json" \
  -d '{"command":"echo Hello"}' http://<windows-ip>:35182/execute

# MCP: Initialize
curl -X POST -H "Content-Type: application/json" \
  -d '{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}' \
  http://<windows-ip>:35182/mcp/initialize

# MCP: List tools
curl -X POST -H "Content-Type: application/json" \
  -d '{}' http://<windows-ip>:35182/mcp/tools/list

# MCP: Call tool
curl -X POST -H "Content-Type: application/json" \
  -d '{"name":"list_windows","arguments":{}}' \
  http://<windows-ip>:35182/mcp/tools/call

# Shutdown server
curl http://<windows-ip>:35182/exit

If you have multiple computers with WinBridgeAgent installed on your LAN, configure your MCP client to manage them:

{ "mcpServers": { "winbridge-test": { "url": "http://192.168.31.3:35182", "description": "Test PC" }, "winbridge-office": { "url": "http://192.168.31.4:35182", "description": "Office PC" } } } ```

See Multi-Computer Setup Guide for details.

Configuration

A config.json file is auto-generated on first run:

{
    "server_port": 35182,
    "auto_port": true,
    "listen_address": "0.0.0.0",
    "language": "en",
    "auto_startup": false,
    "daemon_enabled": true
}

| Key | Description | Default | |-----|-------------|---------| | server_port | Server listen port | 35182 | | auto_port | Auto-select port if occupied | true | | listen_address | 0.0.0.0 (LAN) or 127.0.0.1 (local only) | 0.0.0.0 | | language | UI language (en / zh-CN) | en | | auto_startup | Start with Windows | false | | daemon_enabled | Enable daemon watchdog | true |

Building from Source

Prerequisites

• macOS (Apple Silicon or Intel)
• CMake 3.20+
• MinGW-w64 cross-compilation toolchain

Install Dependencies

brew install mingw-w64 cmake

Build

# Build all architectures
./scripts/build.sh

# Or build a single architecture manually
mkdir -p build/x64
cd build/x64
cmake ../.. -DCMAKE_TOOLCHAIN_FILE=../../toolchain-mingw-x64.cmake \
            -DCMAKE_BUILD_TYPE=Release
make -j$(sysctl -n hw.ncpu)

Build Outputs

• build/x64/WinBridgeAgent.exe — Windows x64
• build/x86/WinBridgeAgent.exe — Windows x86
• build/arm64/WinBridgeAgent.exe — Windows ARM64

Project Structure

.
├── CMakeLists.txt
├── src/            # C++ source code
├── include/        # Public headers
├── resources/      # Runtime assets and templates
├── scripts/        # Build, test, release scripts
├── docs/           # Documentation
├── tests/          # Test code
├── third_party/    # Vendored dependencies
└── build/          # Build outputs

Security Notes

• Listen Address: Setting 0.0.0.0 allows LAN access; use 127.0.0.1 for local-only
• Firewall: Windows Firewall may block network access; add an exception if needed
• Protected Processes: System-critical processes cannot be terminated (system, csrss.exe, winlogon.exe, etc.)
• Protected Directories: System directories cannot be deleted (C:\Windows, C:\Program Files, etc.)
• Audit Log: All operations are logged

License

This project is licensed under the GNU General Public License v3.0.

Copyright © 2026 WinBridgeAgent Contributors