金大哥 - winbridgeagent MCP 详情

article

README

🚀 WinBridgeAgent

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

🚀 快速开始

从 MCP 注册表安装

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

手动安装

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

有关 OpenClaw + Windows 节点的设置，请参阅 windows-node-install.en.md。

✨ 主要特性

核心特性

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 客户端可以直接安装。

手动安装

从 GitHub Releases 下载最新版本。
运行 WinBridgeAgent-x64.exe（64 位）或 WinBridgeAgent-x86.exe（32 位）。
程序将出现在系统托盘中。
配置你的 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

打开设置 → MCP。
点击 添加新的 MCP 服务器。
填写：
- 名称：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

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

有关 Windows 节点部署的详细步骤（包括 mcporter 配对），请参阅 windows-node-install.en.md。

Cherry Studio

打开设置 → MCP 服务器。
点击 添加服务器。
选择 可流式传输的 HTTP 类型。
将 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 端点均可直接访问。

端点信息

| 方法 | 路径 | 描述 | | ---- | ---- | ---- | | GET | / | API 端点列表 | | GET | /health | 健康检查 | | GET | /status | 服务器状态和信息 | | GET | /disks | 列出所有磁盘驱动器 | | GET | /list?path=<path> | 列出目录内容 | | GET | /read?path=<path> | 读取文件内容 | | GET | /search?path=<path>&query=<q> | 搜索文件内容 | | GET | /clipboard | 读取剪贴板 | | PUT | /clipboard | 写入剪贴板 | | GET | /screenshot | 截图 | | GET | /windows | 列出所有窗口 | | GET | /processes | 列出所有进程 | | POST | /execute | 执行命令 | | GET | /exit | 关闭服务器 | | POST | /mcp/initialize | MCP 初始化 | | POST | /mcp/tools/list | MCP 列出工具 | | POST | /mcp/tools/call | MCP 调用工具 |

配置

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

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

| 键 | 描述 | 默认值 | | ---- | ---- | ---- | | server_port | 服务器监听端口 | 35182 | | auto_port | 端口被占用时自动选择端口 | true | | listen_address | 0.0.0.0（局域网）或 127.0.0.1（仅本地） | 0.0.0.0 | | language | 用户界面语言 (en / zh-CN) | en | | auto_startup | 随 Windows 启动 | 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 进行许可。

winbridgeagent

README

🚀 WinBridgeAgent

🚀 快速开始

从 MCP 注册表安装

手动安装

✨ 主要特性

核心特性

文件与系统操作

进程与窗口管理

电源管理

自动更新

📦 安装指南

从 MCP 注册表安装

手动安装

💻 使用示例

基础用法

📚 详细文档

MCP 客户端配置

Claude Desktop

Cursor

Windsurf

OpenClaw

Cherry Studio

Cline (VS Code)

通用 MCP 客户端

HTTP API

端点信息

配置

从源代码构建

前提条件

安装依赖项

构建

构建输出

项目结构

安全注意事项

📄 许可证

运行方式说明

托管运行

本地运行 / 其它方式