Bridge MCP

🌉 Bridge MCP

适用于任何 AI 的通用 PC 控制

让任何 AI 完全控制你的 Windows PC

功能 • 快速开始 • 配置 • 工具 • 故障排查 • 贡献

---

🔄 持久化机制

Bridge MCP v2.0 会将 Agent 注册信息存储在持久化 JSON 文件中：

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

这意味着：

• ✅ 注册一次，永久可用
• ✅ Claude Code 会话重启后仍然有效
• ✅ 电脑重启后仍然有效
• ✅ 可在所有 AI 客户端中使用

首次设置

1. 启动本地 Agent：

   cd Bridge-MCP
   python local_agent.py

2. Agent 会自动注册自身——无需手动注册！

3. 在任意 Claude 会话中验证：

   Use list_agents() to see registered agents

故障排查

如果看到“没有已连接的 Agent”：

1. 检查 local_agent.py 是否正在运行——它必须在终端中运行
2. **检查运行状况：**使用 check_agent_health() 工具
3. **手动注册：**使用 register_agent("local", "http://127.0.0.1:8006", "My PC")

将本地 Agent 作为后台服务运行

如需始终保持可访问，请将 local_agent 安装为 Windows 服务：

python install_service.py install
python install_service.py start

移除方法：

python install_service.py stop
python install_service.py remove

---

🎯 什么是 Bridge MCP？

Bridge MCP 是一个模型上下文协议（MCP）服务，可让任何 AI完全控制 Windows PC。无论你使用 Claude、ChatGPT、Cursor、Gemini，还是其他任何兼容 MCP 的 AI，Bridge MCP 都能让你：

• 🖥️ 控制应用程序 - 启动、切换、调整大小、关闭任意应用
• 🖱️ 自动化输入 - 鼠标点击、键盘输入、快捷键、滚动
• 📸 查看屏幕 - 截图、检测 UI 元素、获取桌面状态
• 🌐 浏览网页 - 完整的 Chrome 自动化与控制
• ⚡ 运行命令 - PowerShell、CMD、文件操作
• 📋 管理剪贴板 - 复制、粘贴、清空

可以把它想象成让 AI 拥有眼睛和双手来控制你的电脑！

---

✨ 功能

类别	工具	描述
🚀 应用控制	8 个工具	启动、切换、关闭、调整大小、最小化、最大化应用程序
🖱️ 鼠标与键盘	10 个工具	点击、输入、快捷键、滚动、拖动、移动光标
📸 屏幕捕获	7 个工具	截图、桌面状态、查找 UI 元素
⚡ 系统	8 个工具	PowerShell、CMD、文件读写、系统信息
🌐 浏览器	15 个工具	Chrome 控制、标签页、导航、网页抓取
📋 剪贴板	3 个工具	复制、粘贴、清空剪贴板
🔧 实用工具	5 个以上工具	等待、对话框、操作序列

总计：40 多个强大工具，实现完整的 PC 自动化！

---

🏗️ 架构

Bridge MCP 使用中继架构，支持跨平台运行：

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

• bridge_mcp.py - MCP 服务（在本地或 FastMCP Cloud 上运行）
• local_agent.py - 在你的 PC 上执行命令的 HTTP 服务（端口 8006）

---

🔒 企业级安全

Bridge MCP 2.0 包含：

• **身份验证令牌：**使用安全的 Bearer 令牌，防止未经授权的访问。
• **自动配置：**自动生成令牌并将其保存到 agents.json。

🌐 新一代浏览器自动化

借助 Playwright，Bridge MCP 现在可以：

• **点击与输入：**与任意网站元素交互。
• **语义理解：**以编程方式读取页面内容。
• **无头模式：**以不可见或可见的方式运行自动化任务。

🧠 语义计算机视觉

Bridge MCP 能“看见”你的应用：

• UI 树： 可以读取 Windows 应用的辅助功能树。
• 精准定位： 准确知道按钮的位置（不再需要猜测像素）。

🛡️ 安全哨兵（人在回路）

Bridge MCP 现在让你掌控一切：

• 命令拦截： 危险命令（写入文件、运行 shell 脚本）默认会被阻止。
• 审批浮层： 审批请求会直接显示在 AI 活动浮层中，并提供三个选项：
  • ✓ APPROVE - 执行这条命令
  • ✗ DENY - 阻止这条命令
  • ✓ ALWAYS APPROVE - 禁用安全模式，并批准所有后续命令
• 控制面板： 在 http://localhost:8006 查看所有待处理请求
• 安全模式开关： 随时通过 Web 控制面板开启或关闭安全模式
• 安心使用： 你可以放心让 Agent 运行，不必担心它删除你的文件。

👁️ 终结者视觉（实时可观测性）

实时查看 AI 所看到的内容：

• 实时视频流： 控制面板提供低延迟的 1080p MJPEG 桌面视频流。
• 语义叠加层： 绿色边界框会标出 AI 检测到的每个按钮、链接和窗口。
• 即时调试： 直观确认 AI 是否找到了正确的“Submit”按钮。

📚 全面支持 MCP 规范

Bridge MCP 现在实现了完整的模型上下文协议规范：

Resources API

将桌面数据公开为可寻址资源：

• desktop://screenshot/latest - 当前屏幕截图
• desktop://windows - 已打开窗口列表
• desktop://logs - Agent 命令日志
• file:///{path} - 读取任意桌面文件
• desktop://session/context - 最近的会话历史

Prompts API

预置工作流模板，实现一键自动化：

• automate_desktop_task - 分步任务自动化
• debug_error - 交互式错误调试
• web_automation - Playwright 网页工作流

会话记忆

永不丢失上下文：

• 跨重启保存最近 100 条命令
• 为 AI 提供最近的会话历史
• 支持“从上次中断处继续”的工作流

---

🚀 快速开始

步骤 1：克隆代码仓库

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

步骤 2：安装依赖项

pip install -r requirements-local.txt

注意： Playwright 浏览器（约 100MB）会在首次使用时自动安装，无需手动设置！

步骤 3：启动本地 Agent

python local_agent.py

保持此终端打开！Agent 将显示：

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

步骤 4：配置你的 AI 客户端

请参阅下方的配置，了解 Claude Desktop、Cursor 或 VS Code 的设置方法。

步骤 5：注册你的 Agent

在 AI 对话中注册本地 Agent：

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") 等任意工具。

---

🔧 配置

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"]
    }
  }
}

远程访问（可选）

如需从任何地方控制你的电脑，可使用 ngrok 暴露本地 Agent：

ngrok http 8006

然后在注册时使用 ngrok URL（例如 https://xxxx.ngrok.io）作为 callback_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()

---

💡 使用示例

示例 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：在 Google 上搜索

User: Search for "Bridge MCP" on Google

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

---

🔧 故障排除

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 - 更改任何配置后，请完全关闭并重新打开。

本地 Agent 未收到命令

1. 确保 local_agent.py 正在终端中运行（请保持终端打开！）
2. 注册 Agent 时，确认回调 URL 正确
3. 本地使用：http://127.0.0.1:8006
4. 远程访问：使用 ngrok（ngrok http 8006），并使用 ngrok URL

“No agents connected”错误

你需要先注册本地 Agent：

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

Windows 上的 Unicode/Emoji 错误

如果 local_agent.py 因 Unicode 错误而崩溃，可能是终端不支持表情符号。最新版本已修复此问题。

---

☁️ FastMCP Cloud 部署

Bridge MCP 可以部署到 FastMCP Cloud，以便轻松访问：

1. Fork 此仓库
2. 前往 fastmcp.cloud
3. 使用 GitHub 登录
4. 从 Fork 的仓库创建项目
5. 设置入口点：bridge_mcp.py
6. 部署！

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

---

🤝 参与贡献

欢迎贡献！你可以通过以下方式提供帮助：

1. Fork 此仓库
2. 创建 功能分支（git checkout -b feature/amazing-feature）
3. 提交 更改（git commit -m 'Add amazing feature'）
4. 推送 到该分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

贡献创意

• 添加更多浏览器支持（Firefox、Edge）
• 添加 Linux 支持
• 添加 macOS 支持
• 添加更多自动化工具
• 改进 UI 元素检测
• 添加 OCR 功能

---

📜 许可证

本项目采用 MIT 许可证授权，详情请参见 LICENSE 文件。

---

🙏 致谢

• FastMCP - 出色的 MCP 框架
• Anthropic - MCP 协议的创建者

---

👤 作者

Barham Agha

• GitHub： @BarhamAgha1

---

⭐ 如果你觉得这个项目有用，请为它点个星！⭐

为 AI 社区倾心打造 ❤️