Bridge MCP

Visual Desktop Bridge - Give any AI full control over Windows to automate apps and inputs.
★ 4MITai-ml
Install

Config snippet generator goes here (5 client tabs)
README

# 🌉 Bridge MCP

### Universal PC Control for Any AI

[![FastMCP](https://img.shields.io/badge/FastMCP-2.0-blue?style=for-the-badge&logo=python)](https://fastmcp.cloud)
[![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)](LICENSE)
[![Python](https://img.shields.io/badge/Python-3.10+-yellow?style=for-the-badge&logo=python)](https://python.org)
[![Windows](https://img.shields.io/badge/Platform-Windows-0078D6?style=for-the-badge&logo=windows)](https://www.microsoft.com/windows)

**Give any AI complete control over your Windows PC**

[Features](#-features) • [Quick Start](#-quick-start) • [Configuration](#-configuration) • [Tools](#-available-tools) • [Troubleshooting](#-troubleshooting) • [Contributing](#-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:**
```bash
   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:
```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:
```
┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│    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