🌉 Bridge MCP

Universal PC Control for Any AI

Give any AI complete control over your Windows PC

Features • Quick Start • Configuration • Tools • Troubleshooting • Contributing

🔄 How Persistence Works

Bridge MCP v2.0 stores agent registrations in a persistent JSON file:

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

This means:

• ✅ Register once, works forever
• ✅ Survives Claude Code session restarts
• ✅ Survives computer reboots
• ✅ Works across all AI clients

First-Time Setup

1. Start the local agent:

   cd Bridge-MCP
   python local_agent.py

2. The agent auto-registers itself - no manual registration needed!

3. Verify in any Claude session:

   Use list_agents() to see registered agents

Troubleshooting

If you see "No agents connected":

1. Check if local_agent.py is running - it must be running in a terminal
2. Check health: Use check_agent_health() tool
3. Manual register: Use register_agent("local", "http://127.0.0.1:8006", "My PC")

Running Local Agent as Background Service

For always-on access, install local_agent as a Windows service:

python install_service.py install
python install_service.py start

To remove:

python install_service.py stop
python install_service.py remove

🎯 What is Bridge MCP?

Bridge MCP is a Model Context Protocol (MCP) server that gives any AI full control over a Windows PC. Whether you're using Claude, ChatGPT, Cursor, Gemini, or any other MCP-compatible AI, Bridge MCP lets you:

• 🖥️ Control Applications - Launch, switch, resize, close any app
• 🖱️ Automate Input - Mouse clicks, keyboard typing, hotkeys, scrolling
• 📸 See the Screen - Screenshots, UI element detection, desktop state
• 🌐 Browse the Web - Full Chrome automation and control
• ⚡ Run Commands - PowerShell, CMD, file operations
• 📋 Manage Clipboard - Copy, paste, clear

Think of it as giving your AI eyes and hands to control your computer!

✨ Features

Total: 40+ powerful tools for complete PC automation!

🏗️ Architecture

Bridge MCP uses a Relay Architecture to work across platforms:

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

• bridge_mcp.py - MCP server (runs locally or on FastMCP Cloud)
• local_agent.py - HTTP server on your PC that executes commands (port 8006)

🔒 Enterprise-Grade Security

Bridge MCP 2.0 includes:

• Auth Tokens: Uses secure Bearer tokens to prevent unauthorized access.
• Auto-Config: Tokens are auto-generated and saved to agents.json.

🌐 Next-Gen Browser Automation

Powered by Playwright, Bridge MCP can now:

• Click & Type: Interact with any website element.
• Semantic Understanding: Read page content programmatically.
• Headless Mode: Run automations invisible or visible.

🧠 Semantic Computer Vision

Bridge MCP "sees" your apps:

• UI Tree: It can read the accessibility tree of Windows apps.
• Precision: Knows exactly where buttons are (no more guessing pixels).

🛡️ Safety Sentinel (Human-in-the-Loop)

Bridge MCP now puts YOU in control:

• Command Interception: Dangerous commands (writing files, running shell scripts) are BLOCKED by default.
• Approval Overlay: Approval requests appear directly in the AI Activity Overlay with three options:
  • ✓ APPROVE - Execute this one command
  • ✗ DENY - Block this command
  • ✓ ALWAYS APPROVE - Disable Safe Mode and approve all future commands
• Dashboard Control: View all pending requests at http://localhost:8006
• Safe Mode Toggle: Switch Safe Mode on/off anytime from the web dashboard
• Peace of Mind: You can leave the agent running without fear of it deleting your files.

👁️ Terminator Vision (Live Observability)

See what the AI sees, in real-time:

• Live Stream: The dashboard features a low-latency 1080p MJPEG stream of your desktop.
• Semantic Overlay: Green bounding boxes highlight every button, link, and window the AI detects.
• Debug Instantly: Visual confirmation that the AI has found the correct "Submit" button.

📚 Full MCP Specification Support

Bridge MCP now implements the complete Model Context Protocol specification:

Resources API

Expose desktop data as addressable resources:

• desktop://screenshot/latest - Current screenshot
• desktop://windows - Open windows list
• desktop://logs - Agent command logs
• file:///{path} - Read any desktop file
• desktop://session/context - Recent session history

Prompts API

Pre-built workflow templates for one-click automation:

• automate_desktop_task - Step-by-step task automation
• debug_error - Interactive error debugging
• web_automation - Playwright web workflows

Session Memory

Never lose context:

• Stores last 100 commands across restarts
• Provides AI with recent session history
• Enables "continue where I left off" workflows

🚀 Quick Start

Step 1: Clone the Repository

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

Step 2: Install Dependencies

pip install -r requirements-local.txt

Note: Playwright browsers (~100MB) auto-install on first use - no manual setup needed!

Step 3: Start the Local Agent

python local_agent.py

Keep this terminal open! The agent will display:

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

Step 4: Configure Your AI Client

See Configuration below for Claude Desktop, Cursor, or VS Code setup.

Step 5: Register Your Agent

In your AI conversation, register the local agent:

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

Step 6: Start Controlling!

Now use any tool like screenshot(), click(100, 200), type_text("Hello"), app_launch("notepad"), etc.

🔧 Configuration

Claude Desktop

1. Open the config file at %APPDATA%\Claude\claude_desktop_config.json

2. Add Bridge MCP:

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

⚠️ Important: Replace the path with the actual location where you cloned the repository!

Example paths:

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

3. Restart Claude Desktop completely (close and reopen)

Cursor

Add to your MCP settings in Cursor preferences with the same configuration format.

VS Code + Claude Code

Create .vscode/mcp.json in your project:

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

Remote Access (Optional)

To control your PC from anywhere, expose the local agent with ngrok:

ngrok http 8006

Then use the ngrok URL (e.g., https://xxxx.ngrok.io) as your callback_url when registering.

🛠️ Available Tools