Chrome MCP Server

Bridge AI agents with your Chrome browser
A Model Context Protocol server that exposes 80 browser capabilities to AI assistants
New MCP: ultra-low latency, instant responses — local round-trips in under 50ms

🇨🇳 Chinese · 🇬🇧 English

Stronger page collection and review workflows — Better support for multi-page content, comment threads, and long lists.

• 🕸️ Recursive page crawling — chrome_crawl_links supports same-origin limits, depth/node caps, retries, field extraction, and partial failure results.
• 💬 Comment and reply extraction — chrome_extract_thread supports scroll loading, nested-item filtering, field mapping, and stop conditions.
• 📊 Stronger long-list collection — Virtual-list, paginated, and multi-tab collection workflows expose independent state, progress snapshots, and diagnostics.
• 🧭 Improved review tools — Page review summaries and expandable sections support finer stop conditions and bounded clicks.
• 🖥️ Desktop assistant and runtime improvements — Better attachment handling, runtime registration, and desktop interaction stability.
• 🔧 All release packages bumped to v2.8.5

See the full changelog for all version changes.

Popup Window	Builder Workflow Editor
Catgirl frosted-glass theme, MCP tools at a glance	Drag-and-drop workflow builder, record & replay automation
Quick Panel	Smart Assistant
In-page quick tools, element picker & actions	Sidepanel chat, Claude / Codex / DeepSeek

chrome-mcp-desktop-2.8.5-win-x64.exe is the portable Windows desktop manager (Tauri 2 + Vue) shipped with the project. It bundles the bridge runtime, so a double-click starts or reuses the local Chrome MCP service without installing Node.js; the Chrome extension still has to be installed and connected using the steps above.

1. Download chrome-mcp-desktop-2.8.5-win-x64.exe from the v2.8.5 Release, put the file in a writable directory, and double-click it to run.
2. The client starts or reuses the local bridge service on http://127.0.0.1:12306 automatically; if the status shows "Waiting for connection", make sure the Chrome extension is loaded and click the connect button in the extension.
3. The console shows service status, Chrome extension connection, Native Host connection, MCP sessions, available tools, running tasks, service endpoints, and error diagnostics; click "Refresh status" or "Health check" to probe again.
4. Closing the window minimizes the client to the system tray. The tray menu can show the client again, run a health check immediately, or choose "Exit client (stop service)" to fully quit and stop the service owned by the client.

The desktop client uses the following MCP endpoints; client configuration is the same as with other installation methods:

Note: chrome-mcp-desktop-2.8.5-win-x64.exe is a GUI management client; do not use it directly as a STDIO MCP command. When you need STDIO, use the bridge runtime EXE with --stdio; open the desktop client when you need to manage the service.

First time? Just complete steps 1 → 4 below. Windows users should use the desktop client; macOS / Linux users, or anyone comfortable with the command line, can use the Node.js route.

1. Download the Chrome extension package from the v2.8.5 Release.
2. Unzip the downloaded .zip file.
3. Open chrome://extensions/ in the Chrome address bar and turn on Developer mode in the top-right corner.
4. Click Load unpacked and select the folder you just unzipped.
5. Click the Chrome MCP icon in the browser toolbar, then click Connect.

Once the extension shows as connected, keep Chrome open and continue to the next step.

1. Download chrome-mcp-desktop-2.8.5-win-x64.exe.
2. Double-click the EXE; the client starts or reuses the local service automatically.
3. Once the client shows "Service status: Running" and "Chrome extension: Connected", you're set.

The desktop client is portable and needs no Node.js installation. It can also show MCP sessions, tool calls, running tasks, and error diagnostics. Closing the window does not stop the service; it minimizes to the system tray.

First install Node.js 24 or later, then run in a terminal:

npm install -g --allow-scripts=@ethanwilkins/mcp-chrome-bridge-2026 @ethanwilkins/mcp-chrome-bridge-2026
mcp-chrome-bridge start

Once the npm install finishes it registers the Native Host Chrome needs. The service listens on http://127.0.0.1:12306 by default.

Windows users who already use the desktop client don't need to repeat the Node.js install and start commands; pick one of the two routes.

In the MCP settings of an AI client such as Claude, Cherry Studio, or Cursor, add a new server, choose Streamable HTTP (some clients write it as streamableHttp), and fill in:

Address: http://127.0.0.1:12306/mcp

If your client needs JSON config, use:

{
  "mcpServers": {
    "chrome-mcp-server": {
      "type": "streamableHttp",
      "url": "http://127.0.0.1:12306/mcp"
    }
  }
}

If your client only supports STDIO, use the bridge runtime, not the GUI desktop client:

{
  "mcpServers": {
    "chrome-mcp-bridge": {
      "command": "D:\\path\\chrome-mcp-bridge-2.8.5-win-x64.exe",
      "args": ["--stdio"]
    }
  }
}

1. Go back to your AI client and refresh the MCP server or reopen the session.

2. Seeing the Chrome MCP tool list (e.g. chrome_get_tab_url, chrome_screenshot) means the connection succeeded.

3. Send a simple test prompt:

   Read the title and URL of my current Chrome tab.

If the desktop client shows "Waiting for connection", first check whether the Chrome extension's Connect button was clicked; you can also open http://127.0.0.1:12306/status?probe=1 in the browser to check the status.

Clients that support the new MCP 2026-07-28 revision can use:

{
  "mcpServers": {
    "chrome-mcp-new": {
      "type": "streamableHttp",
      "url": "http://127.0.0.1:12306/mcp-new"
    }
  }
}

This endpoint works per request and stores no session; lightweight requests can respond in under 50ms. See the /mcp-new endpoint reference for the full headers, _meta structure, and debugging examples. If your client cannot customize new-protocol fields such as Origin, keep using /mcp above.

Clients that need the old SSE protocol should use:

• SSE endpoint: http://127.0.0.1:12306/sse
• Message endpoint: http://127.0.0.1:12306/messages?sessionId=...

After installing the npm package, you can also run:

mcp-chrome-bridge stdio

mcp-chrome-bridge --stdio prefers /mcp-new and falls back to /mcp on failure; if the local service is not running, it starts and reuses it automatically. To force the service to be started by an external process, set CHROME_MCP_AUTOSTART_SERVER=0. The legacy mcp-chrome-stdio entry point remains compatible.

In the repository root, double-click package-desktop-windows.bat and choose Desktop client when prompted. The script checks version consistency and produces:

releases/chrome-mcp-desktop-<version>-win-x64.exe

If you only need the bridge runtime, package-windows.bat builds chrome-mcp-bridge-<version>-win-x64.exe.

By default the service only listens locally and needs no API key. To protect the HTTP / SSE endpoints, set this before starting the service:

$env:CHROME_MCP_API_KEY = "replace-with-a-long-random-key"
mcp-chrome-bridge start

Clients can then send Authorization: Bearer <key> (or x-api-key); the STDIO proxy reads the same environment variable and forwards the Bearer token automatically. HTTP MCP requests without an Origin must carry a valid API key.

By default the service runs at most 8 tool calls concurrently and queues at most 64. Tune this to your machine:

$env:CHROME_MCP_MAX_CONCURRENT_TOOLS = "8"
$env:CHROME_MCP_MAX_QUEUED_TOOLS = "64"
mcp-chrome-bridge start

You can also restrict which tools a client can see and require approval for high-risk tools:

$env:CHROME_MCP_ALLOWED_TOOLS = "chrome_read_page,chrome_get_tab_url,flow.*"
$env:CHROME_MCP_REQUIRE_APPROVAL = "true"
$env:CHROME_MCP_APPROVED_TOOLS = "flow.checkout"

With CHROME_MCP_REQUIRE_APPROVAL=true, high-risk tools such as JavaScript execution, write/publish, file upload, Profile management, and flow.* must also appear in the approval list. Leaving these variables unset preserves the existing compatibility behavior.

More advanced environment variables (extension ID, Origin allowlist, request body size, and Artifact limits) are in the troubleshooting guide.

By default, browser tools continue to control the Chrome you are currently using. For account, cookie, or cache isolation, call chrome_profile first:

{ "action": "create", "name": "Work account", "profileId": "work" }

Then add profileId to a normal browser tool; an isolated Chrome instance starts automatically when needed:

{ "profileId": "work", "url": "https://example.com" }

Use chrome_profile with list, status, diagnostics, launch, stop, or delete to manage profiles. delete removes only the profile configuration and keeps userDataDir, preventing accidental loss of login state. Set CHROME_MCP_EXTENSION_PATH when the isolated Chrome must load a locally built extension.

Click, input, scroll, and navigation actions use a unified balanced pace by default; pass actionPolicy: "fast" or actionPolicy: "human" when needed.

Use chrome_batch to run up to 50 browser calls sequentially as one task; pass profileId to pin the batch to one isolated Profile. Workflow v3 already provides persistent queues plus cron/interval triggers.

mcp-chrome-bridge upgrade 2.3.0 --dry-run
mcp-chrome-bridge upgrade 2.3.0

Upgrades require an exact version and verify npm SHA-512 integrity. If post-install validation of key files fails, the command attempts to roll back to the previous version.

• Native Server: 5 Jest suites, 18 tests (including permission policy and HTTP auth), run by CI with coverage collection
• Chrome Extension: 58 Vitest files, 567 tests, run by CI
• Native / Extension / Shared TypeScript checks passed
• Version consistency: pnpm check:versions
• Tool docs: pnpm check:tool-docs

This test does not use jsdom, fake IndexedDB, or mocked Chrome APIs. Install/load the extension, wait for the Native Host connection, and start the HTTP server first, then run:

pnpm test:chrome-smoke

It checks the Native Host extension connection and browser probe, creates a real MCP session, discovers the catalog, and calls chrome_get_tab_url against the current Chrome tab. Use CHROME_MCP_SMOKE_URL, CHROME_MCP_SMOKE_TIMEOUT_MS, and CHROME_MCP_API_KEY to override the connection settings.

📖 Full API reference: Chinese · English

• 80 MCP Tools — Full browser API coverage, including public chrome_userscript, page collection, and thread extraction tools
• Streamable HTTP (compatibility / early access) + SSE + STDIO — All transports retained
• Smart Assistant — Claude / Codex / DeepSeek
• Semantic Search — Vector DB + local embeddings
• SIMD Acceleration — WASM engine 4-8× faster
• Workflow Recording & Replay — v3 unified architecture (legacy architecture fully migrated)
• Visual Editor — Drag-and-drop workflow builder
• Native Messaging Auto-registration
• Cross-platform Setup — macOS / Linux one-click scripts
• Multi-Profile Isolation — Separate cookies, cache, history and login state
• Persistent Sessions — Restore isolated profiles after browser close
• Unified ActionPolicy — Stable click / input / scroll pacing
• Parallel Sessions — Separate MCP/CDP channels per profile
• Profile Diagnostics — Profile, CDP, MCP, proxy and extension state
• Safe Upgrades — Exact versions, SHA-512 verification and rollback
• Batch and Scheduled Tasks — chrome_batch, workflow queues and cron/interval triggers
• Native Messaging control channel and concurrency governance — Global concurrency cap and global queue cap (CHROME_MCP_MAX_CONCURRENT_TOOLS=8 / CHROME_MCP_MAX_QUEUED_TOOLS=64), serialized writes to the same tab, chrome_batch not consuming extra outer concurrency slots, and /status toolAdmission exposing occupancy and queueing in real time
• Authentication and Permissions — HTTP API keys, tool scopes, and high-risk action approvals
• Live Monitoring Panel — The desktop client shows MCP calls, active requests, latency, and error diagnostics
• Three-Layer Channel Architecture — Native Messaging control channel, Artifact data plane, and localhost WebSocket event channel

• OAuth — Third-party identity authentication and authorization
• Multi-version Chrome Matrix — Run real-browser regression tests across Chrome versions / profiles / environments
• Expanded Product Scope — Hosted browsers and remote CDP

The PDF tool returns Base64 PDF data by default; pass savePdf: true to also save it to Chrome downloads. The page storage tools operate on the target tab's localStorage or sessionStorage, not the extension's own storage.

The project is fully open source and free. If you find it useful, or need technical support / new feature suggestions, feel free to contact the author through the channels below.

Sponsorship unlocks premium extension features 🔓 — your support keeps development going!

WeChat · Chat & Technical Support	Alipay · Sponsorship	WeChat Pay · Sponsorship
Scan to add me on WeChat, get technical support and chat	Scan to sponsor, unlock premium extension features	Scan to sponsor, unlock premium extension features

Contributions welcome! Please read CONTRIBUTING_zh.md before submitting a PR.

MIT — see LICENSE for details.