MCP-ChromeCyber

A Model Context Protocol (MCP) bridge connecting AI agents to a live Chrome browser for automation and authorized security testing. CyberMCP Engine combines a Manifest V3 extension, Bun native host, and Go background worker for DOM inspection, network capture/replay, session-aware browser actions, and bounded background jobs.

This repository starts with a fresh Git history. Required licenses and contributor attribution are retained. Installed dependencies, local environment files, databases, traffic captures, QA reports, rollback copies, build outputs, and optional bulk wordlists are not distributed as source.

Capabilities

Related MCP server: chrome-devtools-mcp

Prerequisites

• Node.js: Version 20 or newer

• Bun: Version 1.3.14 or newer (the host uses built-in bun:sqlite)

• Go: Version 1.22 or newer to build the background worker

• Google Chrome (latest stable release)

• An MCP-compatible client (e.g., VS Code, Claude Desktop, Cursor, Windsurf, or Claude Code CLI)

Quick Start

# 1. Clone the repository
git clone https://github.com/Hakchandara/MCP-ChromeCyber.git
cd MCP-ChromeCyber

# 2. Copy the environment file (sets a deterministic extension ID)
cp app/chrome-extension/.env.example app/chrome-extension/.env.local

# 3. Install dependencies
bun install --frozen-lockfile

# 4. Build all packages
bun run build

# 5. Register the Native Messaging Host
bun run bridge:register:dev

# 6. Start the local MCP server
bun run bridge:start:http

Verify that the server is active:

curl http://127.0.0.1:12306/ping
# Inspect the actual response; a healthy host alone does not prove Chrome is connected.

Choose a Different Port

12306 is the default local port. For a shell-managed launch, set the port in the same environment that starts the bridge:

CHROME_MCP_PORT=12307 bun run bridge:start:http
curl http://127.0.0.1:12307/ping

For an extension-managed bridge, choose the port in the popup before clicking Connect. The value is saved only once the bridge confirms it started. See Port Configuration.

Loading the Chrome Extension

1. Build a candidate without modifying the extension directory Chrome may have open: bun run build:extension:staged.

2. Navigate to chrome://extensions/ in Google Chrome.

3. Enable Developer mode in the top-right corner.

4. Click Load unpacked → select app/chrome-extension/.output/browser-mcp-staged/chrome-mv3/.

5. Ensure the Extension ID matches bdmhjbdmgecbjalpefbpmogmnipbnfhf.

6. Open the extension popup or dashboard and verify the bridge status is active.

The staged build keeps a complete, previously-loaded extension intact if Chrome locks a live asset while WXT builds. It is the recommended release workflow on Windows.

Client Configuration

Start browser work with chrome_get_session_context and reuse the task-owned primary tab. Use exact tab/origin context, keep recovery tokens private, and clean up owned observers and helpers explicitly. Do not create new windows or resend uncertain operations to escape a timeout. Live tool schemas and availability metadata are authoritative; visual diff is currently registered but unavailable. See the agent runbook.

This repository includes pre-configured settings for VS Code and GitHub Copilot. For other environments, refer to the configs below.

VS Code

The .vscode/mcp.json file is included in this workspace:

{
  "servers": {
    "chromeMcp": {
      "type": "http",
      "url": "http://127.0.0.1:12306/mcp"
    }
  }
}

GitHub Copilot CLI

A .mcp.json configuration is included:

{
  "mcpServers": {
    "chromeMcp": {
      "type": "http",
      "url": "http://127.0.0.1:12306/mcp",
      "tools": ["*"]
    }
  }
}

Claude Desktop

Add the following to your configuration file (located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "chromeMcp": {
      "command": "mcp-chrome-stdio"
    }
  }
}

Claude Code CLI

claude mcp add chromeMcp --transport http http://127.0.0.1:12306/mcp

Cursor / Windsurf

Add a new HTTP server in your IDE's MCP settings:

• Name: chromeMcp

• URL: http://127.0.0.1:12306/mcp

For detailed setup instructions, see docs/1-getting-started/02-mcp-client-config.md.

Architecture

flowchart TD
    A[AI Agent]
    B[Native Server]
    C[Chrome Extension]
    D[Go Runner Sidecar]
    E[Job Result Store]

    A -->|HTTP/MCP| B
    B -->|Native Messaging| C
    B -->|HTTP/REST| D
    D -->|jobId| E
    E -.->|Poll status| A

The native server listens on loopback (127.0.0.1) and defaults to port 12306. It supports the following transport options:

• HTTP: POST /mcp + GET /mcp (Standard MCP 2024 transport)

• SSE: GET /sse + POST /messages

• stdio: via the mcp-chrome-stdio binary proxy

Documentation

Optional wordlists and runtime assets

Large SecLists, PortSwigger and custom fuzzing datasets are optional local resources, not bundled repository content. Built-in fallback lists remain available; extended payload-source selections require the corresponding dataset. See local resource setup and review each upstream license before downloading or redistributing it.

The ONNX browser runtime files under app/chrome-extension/workers/ and public/libs/ are required by the similarity worker and are intentionally retained. They are not stale build output. See third-party notices.