金大哥 - bridge-mcp MCP 详情

article

README

🚀 🌉 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 客户端

首次设置

启动本地代理：

cd Bridge-MCP
python local_agent.py

代理自动注册 - 无需手动注册！
在任何 Claude 会话中验证：

Use list_agents() to see registered agents

故障排除

如果看到 "No agents connected"：

检查 local_agent.py 是否正在运行 - 它必须在终端中保持运行状态。
检查健康状态：使用 check_agent_health() 工具。
手动注册：使用 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

打开配置文件 %APPDATA%\Claude\claude_desktop_config.json
添加 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

完全重启 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"

检查路径 - 确保配置文件中的路径指向实际的 bridge_mcp.py 文件。路径必须是绝对路径，并且在 JSON 中使用双反斜杠 (\\)。
手动测试 - 打开命令提示符并运行：

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

它应该保持运行状态（不会立即退出）。按 Ctrl+C 停止。 3. 安装依赖：

pip install fastmcp httpx

重启 Claude Desktop - 在进行任何配置更改后，完全关闭并重新打开。

本地代理未收到命令

确保 local_agent.py 在终端中运行（保持打开状态！）
验证注册代理时的回调 URL 是否正确。
本地使用时：http://127.0.0.1:8006
远程访问时：使用 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 云平台上，方便访问：

分叉此仓库
访问 fastmcp.cloud
使用 GitHub 账号登录
从你的分叉仓库创建项目
设置入口点：bridge_mcp.py
部署！

你的 MCP 将可在以下地址访问：https://your-project.fastmcp.app/mcp

🤝 贡献

欢迎贡献代码！你可以通过以下步骤参与：

分叉仓库
创建功能分支 (git checkout -b feature/amazing-feature)
提交你的更改 (git commit -m 'Add amazing feature')
推送到分支 (git push origin feature/amazing-feature)
打开拉取请求

贡献思路

增加更多浏览器支持（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 社区用心打造 ❤️