dsh-chrome-devtools

中文 | English

Give DeepSeek Harness agents control over a real Chrome browser via chrome-devtools-mcp: navigation, clicking, typing, screenshots, DOM snapshots, console, network requests, performance traces, and cookies.

The only install path is the official dsh plugin one-command install (GitHub source; no clone required). This repository root is itself an official bundle plugin (package.json declares dsh.bundle, cordis.patch.yml is the patch layer): the MCP server row is built into the plugin, so it is ready to use right after install — no extra components to install, no MCP configuration to write.

Features

• One-command install: dsh plugin add github:...; the package is reconciled into the profile's patch-layer stack automatically, zero manual config.
• npx, ready to use: the server runs via npx -y chrome-devtools-mcp@latest — the same convention Claude Code / Claude Desktop / Cursor use for chrome-devtools-mcp. First use downloads it automatically (30-60s); afterwards the npx cache starts it in about a second. No global install, no prerequisites.
• Global: after a host restart every session (including child agents) sees the mcp__chrome-devtools__* tools.
• Real browser: headed or headless Chrome, multiple tabs, cookies, network interception, performance traces.
• Auto-reconnect: the dsh-mcp-client supervisor restarts a crashed server with exponential backoff and a failure budget that prevents infinite restarts.
• Cross-platform: Windows / macOS / Linux; the bundled installer script is zero-dependency (pure Node standard library).

Requirements

Install

dsh plugin --profile web add github:yuzi-ska/DSH-Chrome-devtools

(Replace web with your profile name — tui, headless, etc.)

Then restart the host (dsh web / however you launch it). After the restart every session sees tools such as mcp__chrome-devtools__navigate_page, take_snapshot, take_screenshot, list_console_messages, get_network_request, performance_start_trace (exact set per the server's declaration). No further configuration is needed.

First use downloads the server via npx (~30-60s) and launches Chrome; afterwards it stays resident and starts in about a second.

Uninstall:

dsh plugin --profile web remove dsh-chrome-devtools

Repo installer script (development / local setups)

git clone https://github.com/yuzi-ska/DSH-Chrome-devtools.git
cd DSH-Chrome-devtools

node scripts/install.mjs            # installs into the web profile (local link; edits take effect after restart)
node scripts/install.mjs --check    # environment check (read-only)
node scripts/install.mjs --uninstall

node scripts/install.mjs [options]
  --check             environment check: node/pnpm/dsh/browser/DSH_HOME; writes nothing
  --uninstall         uninstall (dsh plugin remove)
  --profile <name>    target profile (default web)
  --dsh-home <path>   override DSH_HOME (default $DSH_HOME or ~/.dsh)
  --harness <path>    harness repo/install path (runs the CLI via node when dsh is not on PATH)
  --plugin-spec <s>   plugin source (default this repo root; npm name, git source, or local path)
  --package-name <n>  package name used by uninstall (default dsh-chrome-devtools)

Architecture

Harness (profile composition)
   │
   │  bundle plugin patch layer (this repo's cordis.patch.yml)
   ▼
@deepseek-ai/dsh-mcp-client row (stdio, shipped with Harness; config built into the plugin)
   │
   ▼
chrome-devtools-mcp server (npx -y chrome-devtools-mcp@latest, spawned by the host; first-run auto download, then cache hit)
   │
   │  Chrome DevTools Protocol
   ▼
One shared Chrome instance (auto-launches the locally installed Chrome/Chromium/Edge)

• Every MCP tool is registered on ctx.tools as mcp__chrome-devtools__<tool> and called like a native tool by the model.
• One profile mounts one resident server: all sessions share the same browser.
• If the server crashes, the dsh-mcp-client supervisor reconnects with exponential backoff; after 10 consecutive failures the tools are unregistered (recover by restarting the host).
• Each tool call may run up to 120 seconds (configurable).

Tool capabilities

Per the server's actual declaration (28 tools in the current version):

Configuration reference

The defaults work out of the box; the following are optional (restart the host after editing cordis.patch.yml).

The MCP row (built into the plugin)

- id: mcp-chrome-devtools
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: chrome-devtools     # tool namespace: mcp__chrome-devtools__*
    transport: stdio
    command: npx
    args: ['-y', 'chrome-devtools-mcp@latest']
    toolCallTimeoutMs: 120000
    failOnStartupError: false

chrome-devtools-mcp server options (put them in args)

See the official docs/cli.md for the full list.

Sharing semantics

• Tools register in the host composition: every agent under the profile (including child agents) sees them.
• All sessions share one browser and server process, so browser state (tabs, cookies, console buffer) is visible across sessions.
• To isolate browser contexts: change serverName and args (e.g. --isolated or a separate --user-data-dir) in another instance.

Security notes

• Browser capability is shell-level trust: it can read/write cookies, issue arbitrary requests, and reach internal networks. Use it only with trusted sessions.
• Page content (DOM snapshots, console, response bodies) enters the model context and session logs — beware sensitive pages.
• In global mode every request carries this tool family's schemas (token cost).
• With failOnStartupError: false, a server in a crash loop burns the reconnect budget and the tools are unregistered — deliberate failure visibility, no infinite restarts.

Troubleshooting

Development

git clone https://github.com/yuzi-ska/DSH-Chrome-devtools.git
cd DSH-Chrome-devtools

# local link install (edits to cordis.patch.yml take effect after restart; no push needed)
node scripts/install.mjs --harness <harness-repo-path>

# verify the composed tree without booting (boot-free)
node <harness>/apps/cli/lib/bin.js --profile web --dump-config | grep -A8 mcp-chrome-devtools

• After pushing, remote install: dsh plugin --profile web add github:yuzi-ska/DSH-Chrome-devtools.
• Internal development notes live in docs/development.md and are excluded from the remote repository (see .gitignore).

References

• ChromeDevTools/chrome-devtools-mcp (the server; tool list and CLI options per its README / docs/cli.md)
• deepseek-ai/deepseek-harness — packages/mcp/mcp-client (the Harness-side MCP client bridge)
• deepseek-ai/deepseek-harness — packages/bundle (bundle plugin mechanism)
• deepseek-ai/deepseek-harness — apps/cli/src/plugin.ts (the dsh plugin command)