WinBridgeAgent

Open-source Windows MCP server for AI assistants. File, clipboard, screenshot, process & power mgmt.
Open source Open in the app JSON README (API)
About

Open-source Windows MCP server for AI assistants. File, clipboard, screenshot, process & power mgmt.
Details

Kind: MCP servers
Topic: Web search, scraping & browser
Publisher: codyard
Origin: official
Category: ferramentas
Transport: desconhecido
Version: 0.5.0
Stars: 12
Forks: 2
Last push: 2026-03-23T04:59:06Z
Repository state: ativo
Language: C++
License: GPL-3.0
Added: 2026-08-29 03:02:37
Updated: 2026-08-29 03:02:37
Origin id: io.github.codyard/winbridgeagent
README

# WinBridgeAgent

[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![Platform: Windows](https://img.shields.io/badge/Platform-Windows%2010%2F11-0078D6?logo=windows)](https://github.com/codyard/WinBridgeAgent)
[![C++17](https://img.shields.io/badge/C%2B%2B-17-00599C?logo=cplusplus)](https://en.cppreference.com/w/cpp/17)
[![MCP Protocol](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-green)](https://modelcontextprotocol.io)
[![GitHub Release](https://img.shields.io/github/v/release/codyard/WinBridgeAgent?include_prereleases&sort=semver)](https://github.com/codyard/WinBridgeAgent/releases)
[![GitHub Stars](https://img.shields.io/github/stars/codyard/WinBridgeAgent?style=social)](https://github.com/codyard/WinBridgeAgent)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.codyard%2Fwinbridgeagent-orange)](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.codyard/winbridgeagent)

[中文文档](README_zh.md)

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](https://registry.modelcontextprotocol.io) 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](https://github.com/codyard/WinBridgeAgent/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`](./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`

```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:

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

### Windsurf

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

```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`](./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:

```json
{
    "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).

```bash
# 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:

```json
{
    "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](docs/MULTI_COMPUTER_SETUP.md) for details.

## Configuration

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

```json
{
    "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

```bash
brew install mingw-w64 cmake
```

### Build

```bash
# 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

```text
.
├── 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](LICENSE).

Copyright © 2026 WinBridgeAgent Contributors