{
  "markdown": "# 🌉 Bridge MCP\n\n### Universal PC Control for Any AI\n\n[![FastMCP](https://img.shields.io/badge/FastMCP-2.0-blue?style=for-the-badge&logo=python)](https://fastmcp.cloud)\n[![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)](LICENSE)\n[![Python](https://img.shields.io/badge/Python-3.10+-yellow?style=for-the-badge&logo=python)](https://python.org)\n[![Windows](https://img.shields.io/badge/Platform-Windows-0078D6?style=for-the-badge&logo=windows)](https://www.microsoft.com/windows)\n\n**Give any AI complete control over your Windows PC**\n\n[Features](#-features) • [Quick Start](#-quick-start) • [Configuration](#-configuration) • [Tools](#-available-tools) • [Troubleshooting](#-troubleshooting) • [Contributing](#-contributing)\n\n---\n\n## 🔄 How Persistence Works\n\nBridge MCP v2.0 stores agent registrations in a **persistent JSON file**:\n\n- **Windows:** `%APPDATA%\\bridge-mcp\\agents.json`\n- **Linux/Mac:** `~/.config/bridge-mcp/agents.json`\n\nThis means:\n- ✅ Register once, works forever\n- ✅ Survives Claude Code session restarts\n- ✅ Survives computer reboots\n- ✅ Works across all AI clients\n\n### First-Time Setup\n\n1. **Start the local agent:**\n```bash\n   cd Bridge-MCP\n   python local_agent.py\n```\n\n2. **The agent auto-registers itself** - no manual registration needed!\n\n3. **Verify in any Claude session:**\n```\n   Use list_agents() to see registered agents\n```\n\n### Troubleshooting\n\nIf you see \"No agents connected\":\n\n1. **Check if local_agent.py is running** - it must be running in a terminal\n2. **Check health:** Use `check_agent_health()` tool\n3. **Manual register:** Use `register_agent(\"local\", \"http://127.0.0.1:8006\", \"My PC\")`\n\n### Running Local Agent as Background Service\n\nFor always-on access, install local_agent as a Windows service:\n```bash\npython install_service.py install\npython install_service.py start\n```\n\nTo remove:\n```bash\npython install_service.py stop\npython install_service.py remove\n```\n\n---\n\n## 🎯 What is Bridge MCP?\n\nBridge 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:\n\n* 🖥️ **Control Applications** - Launch, switch, resize, close any app\n* 🖱️ **Automate Input** - Mouse clicks, keyboard typing, hotkeys, scrolling\n* 📸 **See the Screen** - Screenshots, UI element detection, desktop state\n* 🌐 **Browse the Web** - Full Chrome automation and control\n* ⚡ **Run Commands** - PowerShell, CMD, file operations\n* 📋 **Manage Clipboard** - Copy, paste, clear\n\n> **Think of it as giving your AI eyes and hands to control your computer!**\n\n---\n\n## ✨ Features\n\n| Category | Tools | Description |\n| --- | --- | --- |\n| 🚀 **App Control** | 8 tools | Launch, switch, close, resize, minimize, maximize applications |\n| 🖱️ **Mouse & Keyboard** | 10 tools | Click, type, hotkeys, scroll, drag, move cursor |\n| 📸 **Screen Capture** | 7 tools | Screenshots, desktop state, find UI elements |\n| ⚡ **System** | 8 tools | PowerShell, CMD, file read/write, system info |\n| 🌐 **Browser** | 15 tools | Chrome control, tabs, navigation, web scraping |\n| 📋 **Clipboard** | 3 tools | Copy, paste, clear clipboard |\n| 🔧 **Utilities** | 5+ tools | Wait, dialogs, action sequences |\n\n**Total: 40+ powerful tools for complete PC automation!**\n\n---\n\n## 🏗️ Architecture\n\nBridge MCP uses a **Relay Architecture** to work across platforms:\n```\n┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐\n│    Any AI       │         │  Cloud Relay    │         │  Your Windows   │\n│  (Claude, etc.) │◄───────►│  (bridge_mcp)   │◄───────►│  PC (Agent)     │\n└─────────────────┘         └─────────────────┘         └─────────────────┘\n```\n\n* **bridge_mcp.py** - MCP server (runs locally or on FastMCP Cloud)\n* **local_agent.py** - HTTP server on your PC that executes commands (port 8006)\n\n---\n\n## 🔒 Enterprise-Grade Security\n\nBridge MCP 2.0 includes:\n- **Auth Tokens:** Uses secure Bearer tokens to prevent unauthorized access.\n- **Auto-Config:** Tokens are auto-generated and saved to `agents.json`.\n\n## 🌐 Next-Gen Browser Automation\n\nPowered by **Playwright**, Bridge MCP can now:\n- **Click & Type:** Interact with any website element.\n- **Semantic Understanding:** Read page content programmatically.\n- **Headless Mode:** Run automations invisible or visible.\n\n## 🧠 Semantic Computer Vision\n\nBridge MCP \"sees\" your apps:\n- **UI Tree:** It can read the accessibility tree of Windows apps.\n- **Precision:** Knows exactly where buttons are (no more guessing pixels).\n\n## 🛡️ Safety Sentinel (Human-in-the-Loop)\n\nBridge MCP now puts YOU in control:\n- **Command Interception:** Dangerous commands (writing files, running shell scripts) are BLOCKED by default.\n- **Approval Overlay:** Approval requests appear directly in the AI Activity Overlay with three options:\n  - ✓ **APPROVE** - Execute this one command\n  - ✗ **DENY** - Block this command\n  - ✓ **ALWAYS APPROVE** - Disable Safe Mode and approve all future commands\n- **Dashboard Control:** View all pending requests at `http://localhost:8006`\n- **Safe Mode Toggle:** Switch Safe Mode on/off anytime from the web dashboard\n- **Peace of Mind:** You can leave the agent running without fear of it deleting your files.\n\n## 👁️ Terminator Vision (Live Observability)\n\nSee what the AI sees, in real-time:\n- **Live Stream:** The dashboard features a low-latency 1080p MJPEG stream of your desktop.\n- **Semantic Overlay:** Green bounding boxes highlight every button, link, and window the AI detects.\n- **Debug Instantly:** Visual confirmation that the AI has found the correct \"Submit\" button.\n\n## 📚 Full MCP Specification Support\n\nBridge MCP now implements the complete Model Context Protocol specification:\n\n### Resources API\nExpose desktop data as addressable resources:\n- `desktop://screenshot/latest` - Current screenshot\n- `desktop://windows` - Open windows list\n- `desktop://logs` - Agent command logs\n- `file:///{path}` - Read any desktop file\n- `desktop://session/context` - Recent session history\n\n### Prompts API\nPre-built workflow templates for one-click automation:\n- `automate_desktop_task` - Step-by-step task automation\n- `debug_error` - Interactive error debugging\n- `web_automation` - Playwright web workflows\n\n### Session Memory\nNever lose context:\n- Stores last 100 commands across restarts\n- Provides AI with recent session history\n- Enables \"continue where I left off\" workflows\n\n---\n\n## 🚀 Quick Start\n\n### Step 1: Clone the Repository\n```bash\ngit clone https://github.com/BarhamAgha1/Bridge-MCP.git\ncd Bridge-MCP\n```\n\n### Step 2: Install Dependencies\n```bash\npip install -r requirements-local.txt\n```\n**Note:** Playwright browsers (~100MB) auto-install on first use - no manual setup needed!\n\n### Step 3: Start the Local Agent\n```bash\npython local_agent.py\n```\n\nKeep this terminal open! The agent will display:\n```\nBridge MCP Local Agent running on http://127.0.0.1:8006\n```\n\n### Step 4: Configure Your AI Client\n\nSee [Configuration](#-configuration) below for Claude Desktop, Cursor, or VS Code setup.\n\n### Step 5: Register Your Agent\n\nIn your AI conversation, register the local agent:\n```\nUse register_agent with:\n- agent_id: \"my-pc\"\n- callback_url: \"http://127.0.0.1:8006\"\n- agent_name: \"My Windows PC\"\n```\n\n### Step 6: Start Controlling!\n\nNow use any tool like `screenshot()`, `click(100, 200)`, `type_text(\"Hello\")`, `app_launch(\"notepad\")`, etc.\n\n---\n\n## 🔧 Configuration\n\n### Claude Desktop\n\n1. Open the config file at `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n2. Add Bridge MCP:\n```json\n{\n  \"mcpServers\": {\n    \"bridge-mcp\": {\n      \"command\": \"python\",\n      \"args\": [\"C:\\\\Users\\\\YourName\\\\Path\\\\To\\\\Bridge-MCP\\\\bridge_mcp.py\"]\n    }\n  }\n}\n```\n\n⚠️ **Important:** Replace the path with the **actual location** where you cloned the repository!\n\n**Example paths:**\n- `C:\\\\Users\\\\PC\\\\Desktop\\\\Bridge-MCP\\\\bridge_mcp.py`\n- `D:\\\\Projects\\\\Bridge-MCP\\\\bridge_mcp.py`\n\n3. **Restart Claude Desktop completely** (close and reopen)\n\n### Cursor\n\nAdd to your MCP settings in Cursor preferences with the same configuration format.\n\n### VS Code + Claude Code\n\nCreate `.vscode/mcp.json` in your project:\n```json\n{\n  \"mcpServers\": {\n    \"bridge-mcp\": {\n      \"command\": \"python\",\n      \"args\": [\"C:\\\\Users\\\\YourName\\\\Path\\\\To\\\\Bridge-MCP\\\\bridge_mcp.py\"]\n    }\n  }\n}\n```\n\n### Remote Access (Optional)\n\nTo control your PC from anywhere, expose the local agent with ngrok:\n```bash\nngrok http 8006\n```\n\nThen use the ngrok URL (e.g., `https://xxxx.ngrok.io`) as your callback_url when registering.\n\n---\n\n## 🛠️ Available Tools\n\n<details>\n<summary><b>🚀 App Control Tools</b></summary>\n\n| Tool | Description | Example |\n| --- | --- | --- |\n| `app_launch` | Launch an application | `app_launch(\"notepad\")` |\n| `app_switch` | Switch to open app | `app_switch(\"Chrome\")` |\n| `app_close` | Close an application | `app_close(\"notepad\")` |\n| `app_list` | List all open apps | `app_list()` |\n\n</details>\n\n<details>\n<summary><b>🖱️ Input Tools (Mouse & Keyboard)</b></summary>\n\n| Tool | Description | Example |\n| --- | --- | --- |\n| `click` | Click at coordinates | `click(500, 300)` |\n| `double_click` | Double-click | `double_click(500, 300)` |\n| `right_click` | Right-click | `right_click(500, 300)` |\n| `type_text` | Type text | `type_text(\"Hello World!\")` |\n| `press_key` | Press a key | `press_key(\"enter\")` |\n| `hotkey` | Keyboard shortcut | `hotkey(\"ctrl,c\")` |\n| `scroll` | Scroll | `scroll(\"down\", 3)` |\n| `drag` | Drag and drop | `drag(100, 100, 500, 500)` |\n| `move_mouse` | Move cursor | `move_mouse(500, 300)` |\n\n</details>\n\n<details>\n<summary><b>📸 Screen Tools</b></summary>\n\n| Tool | Description | Example |\n| --- | --- | --- |\n| `screenshot` | Take screenshot | `screenshot()` |\n| `get_desktop_state` | Get full desktop state | `get_desktop_state()` |\n| `get_screen_size` | Get screen dimensions | `get_screen_size()` |\n| `get_mouse_position` | Get cursor position | `get_mouse_position()` |\n\n</details>\n\n<details>\n<summary><b>⚡ System Tools</b></summary>\n\n| Tool | Description | Example |\n| --- | --- | --- |\n| `run_powershell` | Run PowerShell | `run_powershell(\"Get-Process\")` |\n| `run_cmd` | Run CMD command | `run_cmd(\"dir\")` |\n| `file_read` | Read file | `file_read(\"C:/test.txt\")` |\n| `file_write` | Write file | `file_write(\"C:/test.txt\", \"Hello\")` |\n| `file_list` | List directory | `file_list(\"C:/Users\")` |\n\n</details>\n\n<details>\n<summary><b>🌐 Browser Tools (Chrome)</b></summary>\n\n| Tool | Description | Example |\n| --- | --- | --- |\n| `chrome_open` | Open Chrome | `chrome_open(\"https://google.com\")` |\n| `chrome_navigate` | Go to URL | `chrome_navigate(\"https://example.com\")` |\n\n</details>\n\n<details>\n<summary><b>🌐 Browser Tools (Playwright - Advanced)</b></summary>\n\n| Tool | Description | Example |\n| --- | --- | --- |\n| `browser_navigate` | Go to URL | `browser_navigate(\"google.com\")` |\n| `browser_click` | Click element (CSS) | `browser_click(\"#submit-btn\")` |\n| `browser_type` | Type in element | `browser_type(\"#search\", \"hello\")` |\n| `browser_press` | Press key | `browser_press(\"Enter\")` |\n| `browser_content` | Get page text | `browser_content()` |\n| `browser_screenshot`| Browser screenshot | `browser_screenshot()` |\n\n</details>\n\n<details>\n<summary><b>📋 Clipboard Tools</b></summary>\n\n| Tool | Description | Example |\n| --- | --- | --- |\n| `clipboard_copy` | Copy to clipboard | `clipboard_copy(\"Hello\")` |\n| `clipboard_paste` | Get clipboard | `clipboard_paste()` |\n\n</details>\n\n---\n\n## 💡 Usage Examples\n\n### Example 1: Open Notepad and Write Text\n```\nUser: Open notepad and write \"Hello from AI!\"\n\nAI uses:\n1. app_launch(\"notepad\")\n2. wait(1)\n3. type_text(\"Hello from AI!\")\n```\n\n### Example 2: Take a Screenshot\n```\nUser: What's on my screen right now?\n\nAI uses:\n1. screenshot()\n2. [AI analyzes the image and describes what it sees]\n```\n\n### Example 3: Search on Google\n```\nUser: Search for \"Bridge MCP\" on Google\n\nAI uses:\n1. chrome_open(\"https://google.com\")\n2. type_text(\"Bridge MCP\")\n3. press_key(\"enter\")\n```\n\n---\n\n## 🔧 Troubleshooting\n\n### Claude Desktop shows \"Server disconnected\"\n\n1. **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.\n\n2. **Test manually** - Open Command Prompt and run:\n```cmd\n   cd \"C:\\path\\to\\Bridge-MCP\"\n   python bridge_mcp.py\n```\n   It should stay running (not exit immediately). Press Ctrl+C to stop.\n\n3. **Install dependencies**:\n```cmd\n   pip install fastmcp httpx\n```\n\n4. **Restart Claude Desktop** - Fully close and reopen after any config changes.\n\n### Local agent not receiving commands\n\n1. Make sure `local_agent.py` is running in a terminal (keep it open!)\n2. Verify the callback URL is correct when registering the agent\n3. For local use: `http://127.0.0.1:8006`\n4. For remote access: Use ngrok (`ngrok http 8006`) and use the ngrok URL\n\n### \"No agents connected\" error\n\nYou need to register your local agent first:\n```\nregister_agent(\"my-pc\", \"http://127.0.0.1:8006\", \"My PC\")\n```\n\n### Unicode/Emoji errors on Windows\n\nIf `local_agent.py` crashes with Unicode errors, the terminal may not support emojis. This has been fixed in the latest version.\n\n---\n\n## ☁️ FastMCP Cloud Deployment\n\nBridge MCP can be deployed on [FastMCP Cloud](https://fastmcp.cloud) for easy access:\n\n1. Fork this repository\n2. Go to [fastmcp.cloud](https://fastmcp.cloud)\n3. Sign in with GitHub\n4. Create project from your forked repo\n5. Set entrypoint: `bridge_mcp.py`\n6. Deploy!\n\nYour MCP will be available at: `https://your-project.fastmcp.app/mcp`\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Here's how you can help:\n\n1. **Fork** the repository\n2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)\n3. **Commit** your changes (`git commit -m 'Add amazing feature'`)\n4. **Push** to the branch (`git push origin feature/amazing-feature`)\n5. **Open** a Pull Request\n\n### Ideas for Contributions\n\n* Add more browser support (Firefox, Edge)\n* Add Linux support\n* Add macOS support\n* Add more automation tools\n* Improve UI element detection\n* Add OCR capabilities\n\n---\n\n## 📜 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## 🙏 Acknowledgments\n\n* [FastMCP](https://fastmcp.cloud) - The amazing MCP framework\n* [Anthropic](https://anthropic.com) - For creating the MCP protocol\n\n---\n\n## 👤 Author\n\n**Barham Agha**\n\n* GitHub: [@BarhamAgha1](https://github.com/BarhamAgha1)\n\n---\n\n**⭐ If you find this project useful, please give it a star! ⭐**\n\nMade with ❤️ for the AI community\n",
  "bytes": 14626,
  "sha": "c5cd897069a2b3f3dcf472b7d208d71e4d669e2d9c85d3bb06a688c498c40ad6",
  "repo_slug": "barhamagha1/bridge-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_barhamagha1_bridge_mcp_c692a5b8/readme"
}