Skip to main content
Glama

CDP Browser MCP

A shared Chrome browser for multiple AI agents. Log in once, give each agent its own tabs, and attach different request headers to each tab.

  • Shared login: cookies and browser storage persist in a dedicated Chrome profile.

  • Independent tabs: each agent owns its tabs, actions, leases, and downloads.

  • Per-tab headers: use custom headers or named presets without changing another agent's requests.

  • Standard MCP tools: navigate, click, type, snapshot, extract, and manage tabs through official Chrome DevTools MCP.

Requires Node.js 22.12+ and Google Chrome current Stable or newer, including Linux headless=new. This follows the official Chrome DevTools MCP requirements. Other Chromium-based browsers and older Chrome versions are outside the supported baseline.

Official diagnostics use recent CDP commands, including Lighthouse's Network.emulateNetworkConditionsByRule. Chrome 136/146 can pass basic browser operations yet fail those diagnostics; they are not a compatibility target for 0.2.0. Linux CI installs Google's current Stable channel and prints the actual version on every run.

Historical Linux download fix: v0.1.0 incorrectly supplied a page target's browserContextId to default-context download commands, which can reject startup. v0.1.1 omits that parameter for every platform and preserves per-agent download isolation. The 0.2.0 browser baseline is current Stable or newer as stated above. Platform validation and CI distinguish measured results from deployment guidance.

0.2.0: depends on chrome-devtools-mcp 1.13.0 (Apache-2.0). We spawn its MCP executable with --browserUrl pointing at our loopback Chrome; the official server does not launch or choose a profile. This project's orchestration remains MIT; see NOTICE and the upstream license.

The orchestration layer owns Chrome/profile lifecycle, agent↔tab/pageId leases, domain-filtered lane headers, and downloads. Playwright is now a test-only dependency. The extension backend PoC remains a separate draft: daily-browser, explicitly selected tabs, single lane, no CDP port. It is not included in this branch or enabled by a configuration option. See architecture.

Quick start

Install Node.js 22.12+, npm and curl first. Download the installer and run it in one line:

curl -fsSL https://raw.githubusercontent.com/Tsutomu-miku/cdp-browser-mcp/main/scripts/install.sh -o install.sh && sh install.sh

The default is the latest GitHub Release. Pin a published tag and choose a no-root prefix:

curl -fsSL https://raw.githubusercontent.com/Tsutomu-miku/cdp-browser-mcp/main/scripts/install.sh -o install.sh && VERSION=v0.2.0 NPM_CONFIG_PREFIX="$HOME/.local" sh install.sh
export PATH="$HOME/.local/bin:$PATH"
cdp-browser-mcp --version

v0.2.0 is an example: choose a published tag that contains cdp-browser-mcp-<version>.tgz. The installer downloads that prebuilt archive, uses npm as a local installer for its three runtime dependencies and bin link, checks --version, and prints MCP configuration. It never runs sudo. Missing Release assets fail explicitly and do not trigger a source build. See installer options and permissions.

This project does not publish to npmjs. The public npm package with the same name is unrelated. Do not install this project by registry name (npm install -g cdp-browser-mcp or npx cdp-browser-mcp). Runtime dependencies are still fetched from your configured npm registry.

2. Build from a clone

git clone https://github.com/Tsutomu-miku/cdp-browser-mcp.git
cd cdp-browser-mcp
npm ci
npm run build
node dist/cli.js --version

See development to install your own built archive as a command.

Related MCP server: personae

Connect your agent

Skill with terminal access

Import skills/cdp-browser-mcp into your agent's skill library. The skill uses the CLI directly, so an agent with terminal access does not need an MCP configuration or browser extension. Each execution uses a unique agent ID, shares the dedicated browser's login, and releases only its own tabs when finished.

cdp-browser-mcp open --agent task-123 --json
cdp-browser-mcp navigate https://example.com --agent task-123 --tab <tab-id>
cdp-browser-mcp reclaim --agent task-123

Use the returned tabId from open. Browser actions print snapshots or visible text; --json returns structured results. Execution output stays in the agent's existing terminal/tool log. The skill does not add a UI panel or install software by itself.

MCP tools

Add this to your client's MCP configuration:

{
  "mcpServers": {
    "browser": {
      "command": "cdp-browser-mcp",
      "args": ["mcp", "--agent", "agent-a"]
    }
  }
}

The MCP server starts the shared browser automatically. Give each client a different --agent ID; clients using the same data directory share one browser and login session.

For Codex, add to ~/.codex/config.toml:

[mcp_servers.browser]
command = "cdp-browser-mcp"
args = ["mcp", "--agent", "codex"]

Node.js and the prefix's bin directory must be on the MCP client's PATH. If the client does not inherit your shell PATH, use the installed command's absolute path. See client configuration.

Log in once

cdp-browser-mcp open https://example.com

Log in in the dedicated Chrome window. Other agents share that session. macOS opens a visible browser by default; Linux defaults to headless. To use a visible browser on Linux, start it with launch --headed in a graphical session.

The browser stays running when an MCP client exits. Its login state is stored in ~/.local/state/cdp-browser-mcp, independently of your everyday Chrome profile.

cdp-browser-mcp status
cdp-browser-mcp stop

Per-tab headers

Set headers for all tabs opened by an MCP client, with an explicit hostname allowlist:

{
  "mcpServers": {
    "blue": {
      "command": "cdp-browser-mcp",
      "args": [
        "mcp",
        "--agent",
        "agent-a",
        "--header-domains",
        "[\"example.com\",\"*.example.com\"]",
        "--headers",
        "{\"x-lane\":\"blue\"}"
      ]
    },
    "green": {
      "command": "cdp-browser-mcp",
      "args": [
        "mcp",
        "--agent",
        "agent-b",
        "--header-domains",
        "[\"example.com\",\"*.example.com\"]",
        "--headers",
        "{\"x-lane\":\"green\"}"
      ]
    }
  }
}

For reusable presets, use --config and --lane. No configuration file is needed for the default setup. Headers require headerDomains or --header-domains; requests to other hosts carry none of the configured lane keys.

Tools

Tool

Purpose

browser_navigate

Open a URL and return an accessibility snapshot

browser_click / browser_type

Interact using snapshot refs or CSS selectors

browser_snapshot / browser_extract

Read the current page

browser_tabs / browser_close

Manage this agent's tabs

browser_downloads

List this agent's downloads

browser_devtools

Owned-page screenshot, network/console, Lighthouse, trace

browser_lease

Extend the current tab's lease

Tool names follow Playwright MCP conventions. This project provides a subset, with tab ownership and shared-session behavior added.

Limits

SharedWorker is disabled and ServiceWorker registration is rejected before document scripts run. Those workers belong to an origin, so their background traffic cannot safely inherit a single tab's headers. Sites that require offline caches, push, or other ServiceWorker features may not work.

Cookies and same-origin storage are shared intentionally: logging out affects every agent. Tab ownership prevents accidental interference between trusted agents; it is not a security sandbox. Custom headers accompany HTTP(S) requests only to the explicitly allowlisted hostnames; validate that list before sending sensitive values. WebSocket and WebTransport traffic is outside the header isolation guarantee.

Documentation

License: MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A multi-agent orchestrator that enables multiple AI agents to share a single Chrome browser instance with tab isolation and shared state. It preserves local browser data like cookies and logins while allowing concurrent agent sessions through the official Playwright MCP.
      10
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to control isolated Chromium browser identities, allowing per-account navigation, interaction, and inspection through MCP without requiring Node or CLI installation.
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to control and inspect the user's actual Chrome browser via MCP, preserving login sessions and isolating agent tasks in background tab groups without disrupting the user's workflow.
      226 npm
      MIT