Ghost Bridge MCP

Ghost Bridge is an AI co-pilot tool that does not require restarting Chrome. It directly connects to the Chrome DevTools protocol through a browser extension to enable real-time debugging, network analysis, page perception, and DOM automation operations.

Developer tools Browser automation #Browser debugging #AI automation #Network analysis #DOM operation .JavaScript

rating : 2 points

downloads : 4.9K

update time : 2026-03-12

Open Site

What is Ghost Bridge?

Ghost Bridge is an innovative combination of a Chrome extension and an MCP server that allows an AI assistant (such as Claude) to directly interact with the Chrome browser you are currently using. Unlike traditional automation tools, it does not require starting a new browser instance but directly connects to your existing browser session, achieving a truly zero-restart experience.

How to use Ghost Bridge?

Using Ghost Bridge is very simple: First, install the global npm package and initialize the configuration. Then, load the extension in Chrome. Finally, connect through an AI assistant (such as Claude Desktop). Once the connection is successful, the AI can directly control your browser and perform operations such as debugging, taking screenshots, and filling out forms.

Use cases

Ghost Bridge is particularly suitable for the following scenarios: 1) Real-time web page debugging and troubleshooting; 2) Automated testing and form filling; 3) Web page content scraping and analysis; 4) Performance monitoring and optimization; 5) Collaborating with an AI assistant to complete web-related tasks.

Main features

Zero-configuration connection

Bypass the traditional --remote-debugging-port configuration and directly capture the browser's DevTools protocol through the Chrome extension for plug-and-play.

Debugging without source map

Debug directly in the compressed production code and locate problems through code snippet extraction, string search, and coverage analysis.

Deep network analysis

Comprehensively capture requests and responses, support multi-dimensional filtering and response body inspection to help analyze network performance issues.

Visual perception

Capture high-quality screenshots of the full screen or a specific area and extract page structure data (titles, links, forms, buttons, etc.).

DOM physical operation

Support physical-level UI operations such as clicking, inputting, and form submission, and be fully compatible with modern front-end frameworks such as React, Vue, Angular, and Svelte.

Performance diagnostics

Obtain detailed engine metrics: JavaScript heap memory, layout recalculation, web core metrics (TTFB/FCP/LCP), and resource loading speed.

Multi-client support

The built-in singleton manager automatically coordinates multiple MCP clients to share a single Chrome transport connection.

Advantages

No need to restart the browser and maintain the existing session state

Debug directly in the production environment without source map

Support complex interactions of modern front-end frameworks

Multiple AI clients can collaborate simultaneously

Simple installation and configuration, user-friendly experience

Limitations

The Chrome extension may be suspended after a long period of inactivity

Manually opening DevTools (F12) may cause connection conflicts

Large performance overhead when beautifying large single-line code files

Strict cross-domain iframe content may not be captured

How to use

Installation and initialization

First, install Ghost Bridge globally via npm, and then run the initialization command to automatically configure the MCP client and prepare the extension directory.

Load the Chrome extension

Open the Chrome browser, go to the extension management page (chrome://extensions), enable developer mode, and then load the unpacked extension.

Connect to the browser

Click the Ghost Bridge icon in the browser toolbar, click the connect button, and wait for the status to change to ✅ ON.

Start using

Open Claude Desktop or your AI assistant. All tools are now ready for use.

Usage examples

Automated form filling

Let the AI automatically fill out the login form and submit it to verify whether the login process is normal.

Web page error debugging

When a JavaScript error occurs on the web page, let the AI help locate and diagnose the problem.

Performance analysis

Analyze the web page loading performance and find out the performance bottlenecks.

Frequently Asked Questions

Which browsers does Ghost Bridge support?

Do I need to connect for each tab?

Is Ghost Bridge secure? Will it leak my browsing data?

What should I do if the extension is disconnected?

Which AI assistants are supported?

Related resources

GitHub repository

View the source code, submit issues, and contribute

npm package page

View the latest version and installation statistics

MCP protocol documentation

Understand the technical details of the Model Context Protocol

Chrome extension development documentation

Learn about Chrome extension development

🚀 Ghost Bridge

Zero-restart Chrome AI Copilot that subverts your workflow, allowing AI to seamlessly take over the browser you're already using for real-time debugging, visual observation, and interactive manipulation without launching a new Chrome instance.

🚀 Quick Start

1. Install & Initialize

# Install globally
npm install -g ghost-bridge

# Auto-configure MCP (Claude Code, Antigravity, Codex) and prepare the extension directory
ghost-bridge init

Note on other MCP clients (Cursor, Windsurf, Roo): ghost-bridge init attempts to auto-configure supported clients. If your client isn't auto-detected, simply add the following to your client's MCP configuration file (e.g., mcp.json):
{
  "mcpServers": {
    "ghost-bridge": {
      "command": "node",
      "args": ["/absolute/path/to/global/node_modules/ghost-bridge/dist/server.js"]
    }
  }
}

2. Load the Chrome Extension

Open Chrome and navigate to chrome://extensions.
Toggle Developer mode in the top right corner.
Click Load unpacked.
Select the directory: ~/.ghost-bridge/extension.

💡 Tip: Run ghost-bridge extension --open to reveal the directory directly.

3. Connect & Command

Click the Ghost Bridge ghost icon in your browser toolbar.
Click Connect and wait for the status to turn to ✅ ON.
Open Claude Desktop or your Claude CLI. All tools are now primed and ready!

✨ Features

🔌 Zero-Config Attach — Bypasses the need for --remote-debugging-port. Captures Chrome's native DevTools Protocol directly via an extension.
🔍 No-Sourcemap Debugging — Slice code fragments, perform string searches, and analyze coverage to pinpoint bugs straight in minified production code.
🌐 Deep Network Analysis — Comprehensive capture of requests/responses with multi-dimensional filtering and response body inspection.
📸 Visual & Structural Perception — Full-page or clipped high-fidelity screenshots paired with structural data extraction (titles, links, forms, buttons).
🎯 DOM Physical Manipulation — Empowers AI to click, type, and form-submit with CDP-level physical simulation. Fully compatible with complex SPAs (React/Vue/Angular/Svelte).
📊 Performance Diagnostics — Get granular engine metrics: JS Heap, Layout recalculations, Web Vitals (TTFB/FCP/LCP), and resource loading speeds.
🔄 Multi-Client Mastery — Built-in singleton manager automatically coordinates multiple MCP clients sharing a single Chrome transport.

🛠️ Tool Arsenal

🔍 Core Debugging

Tool	Capability
`get_server_info`	Retrieves server instance status, WebSocket ports, and client roles.
`get_last_error`	Aggregates recent exceptions, console errors, and failed network requests with mapped locators.
`get_script_source`	Pulls raw script definitions. Supports URL-fragment filtering, specific line targeting, and beautification.
`coverage_snapshot`	Triggers a quick coverage trace (1.5s default) to identify the most active scripts on the page.
`find_by_string`	Scans page script sources for keywords, returning a 200-character context window.
`symbolic_hints`	Gathers context clues: Resource lists, Global Variable keys, LocalStorage schema, and UA strings.
`eval_script`	Executes raw JavaScript expressions in the page context. (Use with caution)

🌍 Network Intelligence

Tool	Capability
`list_network_requests`	Lists captured network traffic. Supports filtering by URL, Method, Status Code, or Resource Type.
`get_network_detail`	Dives deep into a specific request's Headers, Timing, and optional Response Body extraction.
`clear_network_requests`	Wipes the current network capture buffer.

📸 Page Perception

Tool	Capability
`capture_screenshot`	Captures the viewport or emulates full-page scrolling screenshots.
`get_page_content`	Extracts raw text, sanitized HTML, or structured actionable data representations.

🎯 Interactive Automation (DOM)

Tool	Capability
`get_interactive_snapshot`	Scans for visible interactive elements, returning a concise map `[e1, e2...]`. Pierces open Shadow DOMs.
`dispatch_action`	Dispatches physical UI actions (click, fill, press, hover) against targeted element references (e.g., `e1`).

Example Agent Workflow:

AI: get_interactive_snapshot ➝ [{ref:"e1", tag:"input", placeholder:"Search..."}, {ref:"e2", tag:"button", text:"Login"}]
AI: dispatch_action({ref: "e1", action: "fill", value: "hello"})
AI: dispatch_action({ref: "e2", action: "click"})
AI: capture_screenshot to verify state changes.

📊 Performance Profiling

Tool	Capability
`perf_metrics`	Collects layered performance data (Engine Metrics, Web Vitals, and Resource Load Summaries).

⚙️ Configuration

Setting	Default	Description
Base Port	`33333`	WS port. Auto-increments if occupied.
Token	Monthly UUID	Local WS auth token, auto-rotates on the 1st of every month.
Auto Detach	`false`	Keeps debugger attached to actively buffer invisible exceptions and network calls.

Environment Variables:

GHOST_BRIDGE_PORT — Override base port.
GHOST_BRIDGE_TOKEN — Override connection token.

🏗️ Architecture

graph LR
    A[Claude CLI/Desktop] <-->|stdio| B(MCP Server\nserver.js)
    B <-->|WebSocket| C(Chrome Extension\nbackground.js)
    C <-->|CDP| D[Browser Tab\nTarget Context]

MCP Server: Spawned by Claude via standard I/O streams. Orchestrates WS connections.
Chrome Extension (MV3): Taps into chrome.debugger API. Utilizes an Offscreen Document to prevent WS hibernation.
Singleton Design: If multiple agents spawn servers, the first becomes the master bridge while subsequent instances chain transparently as clients.

⚠️ Known Limitations

Service Workers Suspending: MV3 background workers may suspend. We've built robust auto-reconnection logic, but prolonged inactivity might require re-toggling.
DevTools Conflict: If you manually open Chrome DevTools (F12) on the target tab, chrome.debugger.attach may be rejected.
Beautify Overhead: Beautifying massive single-line bundles is expensive; the server will auto-truncate overly large scripts.
Cross-Origin OOPIF: Elements and errors deeply embedded in strict Cross-Origin Iframes might evade the primary debugger hook without further multi-target attach logic.