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 社区用心打造 ❤️