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 貢獻者