Winbridgeagent

🚀 WinBridgeAgent

WinBridgeAgent 是一个开源的 Windows 本地功能服务，它实现了模型上下文协议（MCP）标准，为 Claude Desktop、OpenAI 等 AI 助手提供可追溯的 Windows 系统操作。

🚀 快速开始

从 MCP 注册表安装

WinBridgeAgent 已发布在 MCP 注册表 上，名称为 io.github.codyard/winbridgeagent。支持该注册表的 MCP 客户端可以直接安装。

手动安装

1. 从 GitHub Releases 下载最新版本。
2. 运行 WinBridgeAgent-x64.exe（64 位）或 WinBridgeAgent-x86.exe（32 位）。
3. 程序将出现在系统托盘中。
4. 配置你的 MCP 客户端（见下文）。

有关 OpenClaw + Windows 节点的设置，请参阅 。

✨ 主要特性

核心特性

• MCP 协议：完整实现模型上下文协议。
• UTF - 8 兼容性：MCP 工具输出采用 UTF - 8 编码，包括非 ASCII 格式的 Windows 路径。
• HTTP API：提供用于远程控制的 HTTP 接口。
• 实时监控：带有实时请求/响应显示的仪表盘窗口。
• 审计日志：完整的操作日志记录。
• 系统托盘：方便的图形化管理界面。
• 灵活配置：可在 0.0.0.0 和 127.0.0.1 监听地址之间切换。
• 自动更新：自动检查 GitHub 版本发布，并支持一键下载。

文件与系统操作

• 文件读取：磁盘枚举、目录列表、文件读取（按行范围）、内容搜索。
• 文件操作：删除、复制、移动、创建目录。
• 剪贴板：通过 HTTP API 读写剪贴板内容（文本、图像、文件）。
• 截图：
  • 全屏截图（HTTP API，PNG/JPEG 格式）
  • 窗口截图（MCP 工具，按窗口标题）
  • 区域截图（MCP 工具，按坐标）

进程与窗口管理

• 窗口管理：列出所有打开的窗口并显示详细信息。
• 进程查询：列出所有正在运行的进程并显示详细信息。
• 进程管理：终止进程、调整优先级（带有受保护进程黑名单）。
• 命令执行：执行系统命令并捕获输出。

电源管理

• 关机：延迟关机、强制关机，可自定义消息。
• 重启：延迟重启、强制重启。
• 休眠与睡眠：系统休眠和睡眠。
• 取消关机：取消计划的关机/重启操作。

自动更新

• 版本检查：自动检查 GitHub 版本发布。
• 更新通知：友好的通知对话框。
• 一键下载：打开 GitHub 版本发布页面。
• 多渠道：稳定版和测试版渠道。
• 多语言：简体中文、英语。

📦 安装指南

从 MCP 注册表安装

WinBridgeAgent 已发布在 MCP 注册表 上，名称为 io.github.codyard/winbridgeagent。支持该注册表的 MCP 客户端可以直接安装。

手动安装

1. 从 GitHub Releases 下载最新版本。
2. 运行 WinBridgeAgent-x64.exe（64 位）或 WinBridgeAgent-x86.exe（32 位）。
3. 程序将出现在系统托盘中。
4. 配置你的 MCP 客户端（见下文）。

💻 使用示例

基础用法

# 服务器状态
curl http://<windows-ip>:35182/health

# 列出磁盘
curl http://<windows-ip>:35182/disks

# 列出目录
curl "http://<windows-ip>:35182/list?path=C:\\"

# 读取文件
curl "http://<windows-ip>:35182/read?path=C:\\test.txt"

# 搜索文件内容
curl "http://<windows-ip>:35182/search?path=C:\\test.txt&query=keyword"

# 读取剪贴板
curl http://<windows-ip>:35182/clipboard

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

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

# 列出窗口
curl http://<windows-ip>:35182/windows

# 列出进程
curl http://<windows-ip>:35182/processes

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

# MCP: 初始化
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: 列出工具
curl -X POST -H "Content-Type: application/json" \
  -d '{}' http://<windows-ip>:35182/mcp/tools/list

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

# 关闭服务器
curl http://<windows-ip>:35182/exit

如果你在局域网中有多台安装了 WinBridgeAgent 的计算机，可以配置 MCP 客户端来管理它们：

{
    "mcpServers": {
        "winbridge-test": {
            "url": "http://192.168.31.3:35182",
            "description": "测试电脑"
        },
        "winbridge-office": {
            "url": "http://192.168.31.4:35182",
            "description": "办公电脑"
        }
    }
}

详细信息请参阅 多计算机设置指南。

📚 详细文档

MCP 客户端配置

WinBridgeAgent 可与任何兼容 MCP 的客户端配合使用。以下是一些流行客户端的设置说明。

⚠️ 重要提示

请将 <windows-ip> 替换为运行 WinBridgeAgent 的 Windows 计算机的 IP 地址（例如 192.168.1.100）。只有当 MCP 客户端在同一台 Windows 机器上运行时，才使用 localhost。

Claude Desktop

编辑 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. 打开 设置 → MCP。
2. 点击 添加新的 MCP 服务器。
3. 填写：
   • 名称：winbridgeagent
   • 类型：http
   • URL：http://<windows-ip>:35182

或者编辑项目根目录下的 .cursor/mcp.json：

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

Windsurf

编辑 ~/.codeium/windsurf/mcp_config.json：

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

OpenClaw

1. 打开 设置 → MCP 服务器。
2. 点击 添加。
3. 设置：
   • 名称：winbridgeagent
   • 传输协议：HTTP
   • URL：http://<windows-ip>:35182

有关 Windows 节点部署的详细步骤（包括 mcporter 配对），请参阅 。

Cherry Studio

1. 打开 设置 → MCP 服务器。
2. 点击 添加服务器。
3. 选择 可流式传输的 HTTP 类型。
4. 将 URL 设置为 http://<windows-ip>:35182。

Cline (VS Code)

编辑 VS Code 设置中的 cline_mcp_settings.json：

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

通用 MCP 客户端

任何支持 HTTP 传输的 MCP 客户端都可以使用以下信息进行连接：

• 服务器 URL：http://<windows-ip>:35182
• 传输协议：HTTP（可流式传输的 HTTP）
• 协议版本：2024 - 11 - 05

HTTP API

服务器监听配置的端口（默认 35182）。

⚠️ 重要提示

开源版本：无需 Bearer Token 身份验证，所有 API 端点均可直接访问。

端点信息

配置

首次运行时会自动生成 config.json 文件：

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

从源代码构建

前提条件

• macOS（Apple Silicon 或 Intel）
• CMake 3.20+
• MinGW - w64 交叉编译工具链

安装依赖项

brew install mingw-w64 cmake

构建

# 构建所有架构
./scripts/build.sh

# 或者手动构建单个架构
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/x64/WinBridgeAgent.exe — Windows x64
• build/x86/WinBridgeAgent.exe — Windows x86
• build/arm64/WinBridgeAgent.exe — Windows ARM64

项目结构

.
├── CMakeLists.txt
├── src/            # C++ 源代码
├── include/        # 公共头文件
├── resources/      # 运行时资产和模板
├── scripts/        # 构建、测试、发布脚本
├── docs/           # 文档
├── tests/          # 测试代码
├── third_party/    # 第三方依赖
└── build/          # 构建输出

安全注意事项

• 监听地址：设置为 0.0.0.0 允许局域网访问；使用 127.0.0.1 仅允许本地访问。
• 防火墙：Windows 防火墙可能会阻止网络访问，如有需要请添加例外。
• 受保护进程：系统关键进程无法终止（如 system、csrss.exe、winlogon.exe 等）。
• 受保护目录：系统目录无法删除（如 C:\Windows、C:\Program Files 等）。
• 审计日志：所有操作都会被记录。

📄 许可证

本项目采用 GNU 通用公共许可证 v3.0 进行许可。

版权所有 © 2026 WinBridgeAgent 贡献者