Bridge MCP

🚀 🌉 Bridge MCP

Bridge MCP 是一個通用的 PC 控制解決方案，它允許任何 AI 對 Windows PC 進行全面控制，為 AI 賦予了控制計算機的“眼睛”和“雙手”，極大拓展了 AI 的應用場景。

🚀 快速開始

步驟 1：克隆倉庫

git clone https://github.com/BarhamAgha1/Bridge-MCP.git
cd Bridge-MCP

步驟 2：安裝依賴

pip install -r requirements-local.txt

注意：首次使用時，Playwright 瀏覽器（約 100MB）會自動安裝，無需手動設置！

步驟 3：啟動本地代理

python local_agent.py

請保持此終端窗口打開！代理將顯示以下信息：

Bridge MCP Local Agent running on http://127.0.0.1:8006

步驟 4：配置 AI 客戶端

有關 Claude Desktop、Cursor 或 VS Code 的設置，請參閱下面的配置部分。

步驟 5：註冊代理

在 AI 對話中，註冊本地代理：

Use register_agent with:
- agent_id: "my-pc"
- callback_url: "http://127.0.0.1:8006"
- agent_name: "My Windows PC"

步驟 6：開始控制！

現在可以使用任何工具，如 screenshot()、click(100, 200)、type_text("Hello")、app_launch("notepad") 等。

✨ 主要特性

類別	工具數量	描述
🚀 應用控制	8 個工具	啟動、切換、關閉、調整大小、最小化、最大化應用程序
🖱️ 鼠標與鍵盤	10 個工具	點擊、輸入、熱鍵、滾動、拖動、移動光標
📸 屏幕捕獲	7 個工具	截圖、獲取桌面狀態、查找 UI 元素
⚡ 系統	8 個工具	運行 PowerShell、CMD 命令，讀寫文件，獲取系統信息
🌐 瀏覽器	15 個工具	控制 Chrome 瀏覽器，管理標籤頁，導航，網頁抓取
📋 剪貼板	3 個工具	複製、粘貼、清空剪貼板
🔧 實用工具	5+ 個工具	等待、處理對話框、執行動作序列

總計：40+ 個強大工具，實現全面的 PC 自動化！

📦 安裝指南

克隆倉庫

git clone https://github.com/BarhamAgha1/Bridge-MCP.git
cd Bridge-MCP

安裝依賴

pip install -r requirements-local.txt

啟動本地代理

python local_agent.py

作為 Windows 服務運行本地代理

若要實現持續訪問，可將 local_agent.py 安裝為 Windows 服務：

python install_service.py install
python install_service.py start

若要移除服務：

python install_service.py stop
python install_service.py remove

💻 使用示例

基礎用法

示例 1：打開記事本並寫入文本

User: Open notepad and write "Hello from AI!"

AI uses:
1. app_launch("notepad")
2. wait(1)
3. type_text("Hello from AI!")

示例 2：截圖

User: What's on my screen right now?

AI uses:
1. screenshot()
2. [AI analyzes the image and describes what it sees]

示例 3：在谷歌上搜索

User: Search for "Bridge MCP" on Google

AI uses:
1. chrome_open("https://google.com")
2. type_text("Bridge MCP")
3. press_key("enter")

📚 詳細文檔

🔄 持久化工作原理

Bridge MCP v2.0 將代理註冊信息存儲在一個持久化的 JSON 文件中：

• Windows：%APPDATA%\bridge-mcp\agents.json
• Linux/Mac：~/.config/bridge-mcp/agents.json

這意味著：

• ✅ 只需註冊一次，永久有效
• ✅ 即使 Claude Code 會話重啟也不受影響
• ✅ 計算機重啟後仍可正常工作
• ✅ 適用於所有 AI 客戶端

首次設置

1. 啟動本地代理：

cd Bridge-MCP
python local_agent.py

2. 代理自動註冊 - 無需手動註冊！
3. 在任何 Claude 會話中驗證：

Use list_agents() to see registered agents

故障排除

如果看到 "No agents connected"：

1. 檢查 local_agent.py 是否正在運行 - 它必須在終端中保持運行狀態。
2. 檢查健康狀態：使用 check_agent_health() 工具。
3. 手動註冊：使用 register_agent("local", "http://127.0.0.1:8006", "My PC")。

🎯 Bridge MCP 是什麼？

Bridge MCP 是一個模型上下文協議（MCP）服務器，它允許任何 AI 對 Windows PC 進行全面控制。無論你使用的是 Claude、ChatGPT、Cursor、Gemini 還是其他任何支持 MCP 的 AI，Bridge MCP 都能讓你：

• 🖥️ 控制應用程序 - 啟動、切換、調整大小、關閉任何應用程序
• 🖱️ 自動化輸入 - 鼠標點擊、鍵盤輸入、熱鍵、滾動操作
• 📸 查看屏幕 - 截圖、檢測 UI 元素、獲取桌面狀態
• 🌐 瀏覽網頁 - 完全自動化控制 Chrome 瀏覽器
• ⚡ 運行命令 - 執行 PowerShell、CMD 命令，進行文件操作
• 📋 管理剪貼板 - 複製、粘貼、清空剪貼板

可以將其視為為你的 AI 賦予了控制計算機的能力！

🏗️ 架構

Bridge MCP 使用中繼架構在不同平臺上工作：

┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│    Any AI       │         │  Cloud Relay    │         │  Your Windows   │
│  (Claude, etc.) │◄───────►│  (bridge_mcp)   │◄───────►│  PC (Agent)     │
└─────────────────┘         └─────────────────┘         └─────────────────┘

• bridge_mcp.py - MCP 服務器（可在本地或 FastMCP 雲平臺上運行）
• local_agent.py - 運行在你 PC 上的 HTTP 服務器，用於執行命令（端口 8006）

🔧 配置

Claude Desktop

1. 打開配置文件 %APPDATA%\Claude\claude_desktop_config.json
2. 添加 Bridge MCP：

{
  "mcpServers": {
    "bridge-mcp": {
      "command": "python",
      "args": ["C:\\Users\\YourName\\Path\\To\\Bridge-MCP\\bridge_mcp.py"]
    }
  }
}

⚠️ 重要提示：請將路徑替換為你實際克隆倉庫的位置！

示例路徑：

• C:\\Users\\PC\\Desktop\\Bridge-MCP\\bridge_mcp.py
• D:\\Projects\\Bridge-MCP\\bridge_mcp.py

3. 完全重啟 Claude Desktop（關閉並重新打開）

Cursor

在 Cursor 偏好設置的 MCP 設置中添加相同格式的配置。

VS Code + Claude Code

在項目中創建 .vscode/mcp.json 文件：

{
  "mcpServers": {
    "bridge-mcp": {
      "command": "python",
      "args": ["C:\\Users\\YourName\\Path\\To\\Bridge-MCP\\bridge_mcp.py"]
    }
  }
}

遠程訪問（可選）

若要從任何位置控制你的 PC，可以使用 ngrok 暴露本地代理：

ngrok http 8006

然後在註冊時使用 ngrok URL（例如 https://xxxx.ngrok.io）作為回調 URL。

🛠️ 可用工具

🚀 應用控制工具

工具	描述	示例
app_launch	啟動應用程序	app_launch("notepad")
app_switch	切換到已打開的應用	app_switch("Chrome")
app_close	關閉應用程序	app_close("notepad")
app_list	列出所有已打開的應用	app_list()

🖱️ 輸入工具（鼠標與鍵盤）

工具	描述	示例
click	在指定座標處點擊	click(500, 300)
double_click	雙擊	double_click(500, 300)
right_click	右鍵點擊	right_click(500, 300)
type_text	輸入文本	type_text("Hello World!")
press_key	按下按鍵	press_key("enter")
hotkey	使用鍵盤快捷鍵	hotkey("ctrl,c")
scroll	滾動操作	scroll("down", 3)
drag	拖動操作	drag(100, 100, 500, 500)
move_mouse	移動鼠標光標	move_mouse(500, 300)

📸 屏幕工具

工具	描述	示例
screenshot	截圖	screenshot()
get_desktop_state	獲取完整桌面狀態	get_desktop_state()
get_screen_size	獲取屏幕尺寸	get_screen_size()
get_mouse_position	獲取鼠標光標位置	get_mouse_position()

⚡ 系統工具

工具	描述	示例
run_powershell	運行 PowerShell 命令	run_powershell("Get-Process")
run_cmd	運行 CMD 命令	run_cmd("dir")
file_read	讀取文件	file_read("C:/test.txt")
file_write	寫入文件	file_write("C:/test.txt", "Hello")
file_list	列出目錄內容	file_list("C:/Users")

🌐 瀏覽器工具（Chrome）

工具	描述	示例
chrome_open	打開 Chrome 瀏覽器	chrome_open("https://google.com")
chrome_navigate	導航到指定 URL	chrome_navigate("https://example.com")

🌐 瀏覽器工具（Playwright - 高級）

工具	描述	示例
browser_navigate	導航到指定 URL	browser_navigate("google.com")
browser_click	點擊指定元素（使用 CSS 選擇器）	browser_click("#submit-btn")
browser_type	在指定元素中輸入文本	browser_type("#search", "hello")
browser_press	按下按鍵	browser_press("Enter")
browser_content	獲取頁面文本內容	browser_content()
browser_screenshot	截取瀏覽器頁面截圖	browser_screenshot()

📋 剪貼板工具

工具	描述	示例
clipboard_copy	複製內容到剪貼板	clipboard_copy("Hello")
clipboard_paste	獲取剪貼板內容	clipboard_paste()

🔧 故障排除

Claude Desktop 顯示 "Server disconnected"

1. 檢查路徑 - 確保配置文件中的路徑指向實際的 bridge_mcp.py 文件。路徑必須是絕對路徑，並且在 JSON 中使用雙反斜槓 (\\)。
2. 手動測試 - 打開命令提示符並運行：

cd "C:\path\to\Bridge-MCP"
python bridge_mcp.py

它應該保持運行狀態（不會立即退出）。按 Ctrl+C 停止。 3. 安裝依賴：

pip install fastmcp httpx

4. 重啟 Claude Desktop - 在進行任何配置更改後，完全關閉並重新打開。

本地代理未收到命令

1. 確保 local_agent.py 在終端中運行（保持打開狀態！）
2. 驗證註冊代理時的回調 URL 是否正確。
3. 本地使用時：http://127.0.0.1:8006
4. 遠程訪問時：使用 ngrok (ngrok http 8006) 並使用 ngrok URL。

"No agents connected" 錯誤

你需要先註冊本地代理：

register_agent("my-pc", "http://127.0.0.1:8006", "My PC")

Windows 上的 Unicode/Emoji 錯誤

如果 local_agent.py 因 Unicode 錯誤崩潰，可能是終端不支持 Emoji。此問題在最新版本中已修復。

☁️ FastMCP 雲部署

Bridge MCP 可以部署在 FastMCP 雲平臺 上，方便訪問：

1. 分叉此倉庫
2. 訪問 fastmcp.cloud
3. 使用 GitHub 賬號登錄
4. 從你的分叉倉庫創建項目
5. 設置入口點：bridge_mcp.py
6. 部署！

你的 MCP 將可在以下地址訪問：https://your-project.fastmcp.app/mcp

🤝 貢獻

歡迎貢獻代碼！你可以通過以下步驟參與：

1. 分叉 倉庫
2. 創建 功能分支 (git checkout -b feature/amazing-feature)
3. 提交 你的更改 (git commit -m 'Add amazing feature')
4. 推送 到分支 (git push origin feature/amazing-feature)
5. 打開 拉取請求

貢獻思路

• 增加更多瀏覽器支持（Firefox、Edge）
• 增加 Linux 支持
• 增加 macOS 支持
• 增加更多自動化工具
• 改進 UI 元素檢測
• 增加 OCR 功能

🔧 技術細節

🔒 企業級安全

Bridge MCP 2.0 包含以下安全特性：

• 認證令牌：使用安全的 Bearer 令牌防止未經授權的訪問。
• 自動配置：令牌會自動生成並保存到 agents.json 文件中。

🌐 下一代瀏覽器自動化

藉助 Playwright，Bridge MCP 現在可以：

• 點擊與輸入：與任何網站元素進行交互。
• 語義理解：以編程方式讀取頁面內容。
• 無頭模式：以不可見或可見模式運行自動化操作。

🧠 語義計算機視覺

Bridge MCP 能夠“看到”你的應用程序：

• UI 樹：它可以讀取 Windows 應用程序的可訪問性樹。
• 高精度：準確知道按鈕的位置（無需再猜測像素位置）。

🛡️ 安全哨兵（人工介入）

Bridge MCP 現在讓你完全掌控：

• 命令攔截：默認情況下，危險命令（寫入文件、運行 shell 腳本）會被阻止。
• 審批覆蓋：審批請求會直接顯示在 AI 活動覆蓋層中，提供三個選項：
  • ✓ 批准 - 執行此命令
  • ✗ 拒絕 - 阻止此命令
  • ✓ 始終批准 - 禁用安全模式並批准所有未來命令
• 儀表盤控制：在 http://localhost:8006 查看所有待處理請求。
• 安全模式切換：可以隨時從 Web 儀表盤切換安全模式的開啟/關閉。
• 安心使用：你可以讓代理持續運行，而無需擔心它會刪除你的文件。

👁️ 終結者視覺（即時可觀測性）

即時查看 AI 所看到的內容：

• 即時流：儀表盤提供低延遲的 1080p MJPEG 桌面即時流。
• 語義覆蓋層：綠色邊框會突出顯示 AI 檢測到的每個按鈕、鏈接和窗口。
• 即時調試：直觀確認 AI 是否找到了正確的“提交”按鈕。

📚 完整 MCP 規範支持

Bridge MCP 現在實現了完整的模型上下文協議規範：

資源 API

將桌面數據作為可尋址資源公開：

• desktop://screenshot/latest - 當前截圖
• desktop://windows - 已打開窗口列表
• desktop://logs - 代理命令日誌
• file:///{path} - 讀取任何桌面文件
• desktop://session/context - 最近會話歷史記錄

提示 API

預構建的工作流模板，實現一鍵自動化：

• automate_desktop_task - 分步任務自動化
• debug_error - 交互式錯誤調試
• web_automation - Playwright 網頁工作流

會話內存

永不丟失上下文：

• 跨重啟保存最後 100 條命令
• 為 AI 提供最近的會話歷史記錄
• 支持“從上次中斷處繼續”的工作流

📄 許可證

本項目採用 MIT 許可證 - 詳情請參閱 LICENSE 文件。

🙏 致謝

• FastMCP - 出色的 MCP 框架
• Anthropic - 創造了 MCP 協議

👤 作者

Barham Agha

• GitHub: @BarhamAgha1

---

⭐ 如果你覺得這個項目有用，請給它點個星！ ⭐

為 AI 社區用心打造 ❤️