io.github.BarhamAgha1/bridge-mcp

Official

by BarhamAgha1 · Python

Bridge MCP

Visual Desktop Bridge - Give any AI full control over Windows to automate apps and inputs.

Gives AI full control of Windows desktop to automate applications and user inputs.

README.md15 KBView on GitHub

🌉 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

Start the local agent:

bash

   cd Bridge-MCP
   python local_agent.py

The agent auto-registers itself - no manual registration needed!
Verify in any Claude session:

code

   Use list_agents() to see registered agents

Troubleshooting

If you see "No agents connected":

Check if local_agent.py is running - it must be running in a terminal
Check health: Use check_agent_health() tool
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:

bash

python install_service.py install
python install_service.py start

To remove:

bash

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

Category	Tools	Description
🚀 App Control	8 tools	Launch, switch, close, resize, minimize, maximize applications
🖱️ Mouse & Keyboard	10 tools	Click, type, hotkeys, scroll, drag, move cursor
📸 Screen Capture	7 tools	Screenshots, desktop state, find UI elements
⚡ System	8 tools	PowerShell, CMD, file read/write, system info
🌐 Browser	15 tools	Chrome control, tabs, navigation, web scraping
📋 Clipboard	3 tools	Copy, paste, clear clipboard
🔧 Utilities	5+ tools	Wait, dialogs, action sequences

Total: 40+ powerful tools for complete PC automation!

🏗️ Architecture

Bridge MCP uses a Relay Architecture to work across platforms:

code

┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│    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

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

bash

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

Step 2: Install Dependencies

bash

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

bash

python local_agent.py

Keep this terminal open! The agent will display:

code

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:

code

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

Open the config file at %APPDATA%\Claude\claude_desktop_config.json
Add Bridge MCP:

json

{
  "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

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:

json

{
  "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:

bash

ngrok http 8006

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

🛠️ Available Tools

<details> <summary>🚀 App Control Tools</summary>

Tool	Description	Example
`app_launch`	Launch an application	`app_launch("notepad")`
`app_switch`	Switch to open app	`app_switch("Chrome")`
`app_close`	Close an application	`app_close("notepad")`
`app_list`	List all open apps	`app_list()`

</details> <details> <summary>🖱️ Input Tools (Mouse & Keyboard)</summary>

Tool	Description	Example
`click`	Click at coordinates	`click(500, 300)`
`double_click`	Double-click	`double_click(500, 300)`
`right_click`	Right-click	`right_click(500, 300)`
`type_text`	Type text	`type_text("Hello World!")`
`press_key`	Press a key	`press_key("enter")`
`hotkey`	Keyboard shortcut	`hotkey("ctrl,c")`
`scroll`	Scroll	`scroll("down", 3)`
`drag`	Drag and drop	`drag(100, 100, 500, 500)`
`move_mouse`	Move cursor	`move_mouse(500, 300)`

</details> <details> <summary>📸 Screen Tools</summary>

Tool	Description	Example
`screenshot`	Take screenshot	`screenshot()`
`get_desktop_state`	Get full desktop state	`get_desktop_state()`
`get_screen_size`	Get screen dimensions	`get_screen_size()`
`get_mouse_position`	Get cursor position	`get_mouse_position()`

</details> <details> <summary>⚡ System Tools</summary>

Tool	Description	Example
`run_powershell`	Run PowerShell	`run_powershell("Get-Process")`
`run_cmd`	Run CMD command	`run_cmd("dir")`
`file_read`	Read file	`file_read("C:/test.txt")`
`file_write`	Write file	`file_write("C:/test.txt", "Hello")`
`file_list`	List directory	`file_list("C:/Users")`

</details> <details> <summary>🌐 Browser Tools (Chrome)</summary>

Tool	Description	Example
`chrome_open`	Open Chrome	`chrome_open("https://google.com")`
`chrome_navigate`	Go to URL	`chrome_navigate("https://example.com")`

</details> <details> <summary>🌐 Browser Tools (Playwright - Advanced)</summary>

Tool	Description	Example
`browser_navigate`	Go to URL	`browser_navigate("google.com")`
`browser_click`	Click element (CSS)	`browser_click("#submit-btn")`
`browser_type`	Type in element	`browser_type("#search", "hello")`
`browser_press`	Press key	`browser_press("Enter")`
`browser_content`	Get page text	`browser_content()`
`browser_screenshot`	Browser screenshot	`browser_screenshot()`

</details> <details> <summary>📋 Clipboard Tools</summary>

Tool	Description	Example
`clipboard_copy`	Copy to clipboard	`clipboard_copy("Hello")`
`clipboard_paste`	Get clipboard	`clipboard_paste()`

</details>

💡 Usage Examples

Example 1: Open Notepad and Write Text

code

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

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

Example 2: Take a Screenshot

code

User: What's on my screen right now?

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

Example 3: Search on Google

code

User: Search for "Bridge MCP" on Google

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

🔧 Troubleshooting

Claude Desktop shows "Server disconnected"

Check the path - Make sure the path in your config points to the actual bridge_mcp.py file. The path must be absolute and use double backslashes (\\) in JSON.
Test manually - Open Command Prompt and run:

cmd

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

It should stay running (not exit immediately). Press Ctrl+C to stop.

Install dependencies:

cmd

   pip install fastmcp httpx

Restart Claude Desktop - Fully close and reopen after any config changes.

Local agent not receiving commands

Make sure local_agent.py is running in a terminal (keep it open!)
Verify the callback URL is correct when registering the agent
For local use: http://127.0.0.1:8006
For remote access: Use ngrok (ngrok http 8006) and use the ngrok URL

"No agents connected" error

You need to register your local agent first:

code

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

Unicode/Emoji errors on Windows

If local_agent.py crashes with Unicode errors, the terminal may not support emojis. This has been fixed in the latest version.

☁️ FastMCP Cloud Deployment

Bridge MCP can be deployed on FastMCP Cloud for easy access:

Fork this repository
Go to fastmcp.cloud
Sign in with GitHub
Create project from your forked repo
Set entrypoint: bridge_mcp.py
Deploy!

Your MCP will be available at: https://your-project.fastmcp.app/mcp

🤝 Contributing

Contributions are welcome! Here's how you can help:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Ideas for Contributions

Add more browser support (Firefox, Edge)
Add Linux support
Add macOS support
Add more automation tools
Improve UI element detection
Add OCR capabilities

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

FastMCP - The amazing MCP framework
Anthropic - For creating the MCP protocol

👤 Author

Barham Agha

GitHub: @BarhamAgha1

⭐ If you find this project useful, please give it a star! ⭐

Made with ❤️ for the AI community

Install

claude_desktop_config.json

{
  "mcpServers": {
    "bridge-mcp": {
      "command": "uvx",
      "args": [
        "bridge-mcp"
      ]
    }
  }
}