chrome-remote-debugging-mcp
MCP server for controlling a running Chrome over the Chrome DevTools Protocol, exposing browser inspection, navigation, JavaScript evaluation, and raw CDP access as tools.
Check Chrome DevTools connectivity with
ping.List open page tabs with
list_tabs.Navigate a tab to a URL with
navigate(opens/reuses a tab).Evaluate JavaScript in a tab with
evaluate, or from a file withevaluate_file; large results can be written tooutput_path.Browse pages through Chrome's accessibility tree with
browse, inspect withbrowse_view, and perform batched actions such as click, type, press, select, check/uncheck, scroll, hover, and wait withbrowse_act.Send arbitrary page-level CDP commands with
cdp_commandas an escape hatch.Close tabs with
close_tab.Optionally auto-launch Chrome, attach to your own Chrome via autoConnect, or reach a remote Chrome through an SSH tunnel.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@chrome-remote-debugging-mcp Navigate to https://example.com"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
chrome-remote-debugging-mcp
MCP server that controls a running Chrome over the Chrome DevTools Protocol (CDP). It connects to Chrome's remote-debugging endpoint and exposes browser control as MCP tools.
Requirements
Python ≥ 3.10
A Chrome/Chromium started with remote debugging:
google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.config/chrome-remote-debugging-mcp"--user-data-diris required: since Chrome 136 the debugging port is not opened for the default profile. The separate profile starts logged out of every site; keep it at a persistent path so logins survive restarts.Alternatively, set
CHROME_LAUNCH=1and let the server start Chrome itself — see Auto-launch Chrome.
Related MCP server: chrome-dev-mcp
Register with an MCP client
Example mcpServers entry:
{
"mcpServers": {
"chrome-remote-debugging": {
"command": "uvx",
"args": ["chrome-remote-debugging-mcp"],
"env": { "CDP_URL": "http://localhost:9222" }
}
}
}Tools
Tool | Args | Returns |
| — |
|
| — |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
navigate and browse open a new tab when tab_id is omitted and return its
id; every other tab-scoped tool requires an explicit tab_id. Close tabs you are
done with via close_tab.
evaluate is meant for short snippets. For a long script, write it to a file and
pass its absolute path to evaluate_file: the file is read on the machine running
the server (not the one running Chrome) and evaluated exactly like an evaluate
expression, with the file named in JS stack traces.
For a large result (e.g. the text of a Jira issue), pass output_path to either
tool: an absolute path (~ is expanded) on the machine running the server. The
value is written there instead of returned — a string as is (UTF-8), anything else
as indented JSON — overwriting any existing file, and the tool returns
{tab_id, path, type, bytes}. On an error nothing is written.
cdp_command is a raw CDP escape hatch: pass any CDP method + params and get
the raw response, for cases the typed tools above don't cover. It runs in the
tab's persistent session, so objectId/nodeId values and domain state (e.g.
after Network.enable) carry over between calls while the tab is open and the
server's connection to Chrome stays up. Events
are not delivered, so a command that waits for the client to answer one hangs
the tab until it is undone or the tab is closed: Fetch.enable (undo with
Fetch.disable), Debugger.pause (Debugger.resume), Target.setAutoAttach
with waitForDebuggerOnStart: true (set it back to false) and
Page.setInterceptFileChooserDialog with enabled: true (set it to false).
Browser.* and Target.* are not supported; their results are undefined.
On any Chrome connection problem a tool returns {"error": "..."} instead of
crashing.
Browsing a page
browse returns what a person would see, not HTML. The view is built from
Chrome's accessibility tree, so it covers closed shadow DOM and cross-origin
iframes — content a JavaScript DOM walk cannot reach — while hidden elements are
filtered out by Chrome itself.
url https://news.ycombinator.com/
title Hacker News
link#1 -> #
link#2 "Hacker News" -> /news
link#3 "new" -> /newest
link#4 "past" -> /front
link#5 "comments" -> /newcomments
link#6 "ask" -> /ask
link#7 "show" -> /show
link#8 "jobs" -> /jobs
link#9 "submit" -> /submit
link#10 "login" -> /login?goto=news
| | | |
|---|---|---|
| 1. | link#11 -> /vote?id=49546753&how=up&goto=news | link#12 "Pre-Release of Polars 2.0" -> https://pola.rs/posts/announcing-polars-2/ link#13 "pola.rs" -> /from?site=pola.rs |
| | 107 points by link#14 "komape" -> /user?id=komape link#15 "2 hours ago" -> /item?id=49546753 link#16 "hide" -> /hide?id=49546753&goto=news link#17 "18 comments" -> /item?id=49546753 | |
…(the unedited opening of a real view, rendered from the front-page tree captured in
tests/fixtures/hn.json.gz.
Numbering and printing order follow document order, not Chrome's
breadth-first Accessibility.getFullAXTree array, so the site header's nine
navigation links print first — refs #1-#10 — and only then the front
page's stories. Those sit in a semantic <table>, so they print as a Markdown
table: each cell's content joined on one line, links keeping their refs. The
stories, ref numbers and comment counts will differ on any given run; the
front page changes constantly.)
A blank line separates blocks and indentation shows nesting, one level per
block of ancestry — see block_path in ax.py. A table (table, grid,
treegrid) prints as a Markdown grid: its first row is the header when it
holds a columnheader, otherwise the header is left blank; short rows are
padded (the tree carries no colspan), rows with no content are dropped, and a
| inside a cell is escaped as \|.
A link shows where it goes after ->: just the path when it stays on the
page's own origin, just #fragment when it points at the page itself (a
href="#" tab or toggle prints as -> #), the full url otherwise; a url
longer than 120 characters is cut with …. A combobox/listbox lists its
options in braces — all of them, e.g. {один | два} — and a
slider/spinbutton shows its bounds as [min..max].
Every interactive
element Chrome can address carries a #N ref (the rare element with no backend
DOM id — see the invariants in CLAUDE.md — renders without one rather than
taking a number it can't be resolved back through). Pass those refs to
browse_act, which runs a batch of actions and returns one new view:
[{"do": "type", "ref": 9, "text": "polars"},
{"do": "press", "key": "Enter"},
{"do": "wait_for", "text": "results", "timeout": 5},
{"do": "click", "ref": 20}]Supported actions: click, type, press, select, check, uncheck,
scroll, hover, wait_for. Actions are dispatched as real CDP input events,
so sites that check isTrusted behave normally — except select: a native
<option> list is browser chrome, not page content, so its value is set
programmatically and input/change events are dispatched for the page to see.
Refs live for one view. Numbering follows document order, so any change
earlier in the page shifts every later number. Refs from an older view are
rejected with a stale or not in the current view error rather than clicking
the wrong thing. Take a new view and use its numbers.
Refs in a child frame can be seen but not acted on. The view is built from
every frame — including cross-origin iframes, which a JavaScript DOM walk
cannot reach at all — so an element inside one still gets a #N ref and
prints in the view. But every action is dispatched in the page target's own
session, which only ever reaches the main frame's renderer; a node in a
same- or cross-origin child frame lives in a different coordinate space (and,
cross-origin, a different renderer process) this tool has no way to address.
Acting on such a ref is refused with an explicit "not the main frame" error
rather than being sent anyway to fail later as a misleading stale ref.
For a page whose content arrives after load — most single-page applications —
browse waits for the document, not for the content. Use an explicit
wait_for step.
Configuration
Env var | Default | Meaning |
|
| Chrome remote-debugging origin |
| unset (off) |
|
| unset (off) |
|
|
| Chrome profile directory holding |
| unset (off) | Log every tool call — arguments, result, duration — to a file. |
Auto-launch Chrome (optional)
{
"mcpServers": {
"chrome-remote-debugging": {
"command": "uvx",
"args": ["chrome-remote-debugging-mcp"],
"env": { "CHROME_LAUNCH": "1" }
}
}
}The first tool call starts Chrome (google-chrome, google-chrome-stable,
chromium or chromium-browser, whichever is first on PATH) with its own
persistent profile at ~/.cache/chrome-remote-debugging-mcp/chrome-profile
and a debugging port Chrome picks itself. Log in to sites once in that window;
the logins survive restarts. If Chrome is closed, the next tool call starts it
again. Several MCP sessions share the same Chrome; it is closed when the
session that started it exits.
Do not set CDP_URL or SSH_PROXY_TO together with CHROME_LAUNCH — the
server refuses to start.
Attach to your own Chrome (autoConnect)
Use your everyday Chrome, with its logins, instead of a separate debugging profile:
{
"mcpServers": {
"chrome-remote-debugging": {
"command": "uvx",
"args": ["chrome-remote-debugging-mcp"],
"env": { "CHROME_AUTOCONNECT": "1" }
}
}
}Open chrome://inspect/#remote-debugging in that Chrome and switch remote
debugging on. The server finds Chrome through <profile>/DevToolsActivePort
(CHROME_USER_DATA_DIR, default ~/.config/google-chrome); Chrome serves no
HTTP in this mode. The first tool call makes Chrome show an Allow dialog;
click it. That is once per server process: the connection then stays open.
Debugging is off. The tool returns "Chrome is not accepting debugging connections: ask the user to enable remote debugging in chrome://inspect/#remote-debugging, then call the tool again; that call makes Chrome show an "Allow" dialog for the user to click". Switch it on, call again and click Allow in the dialog that call opens.
"has not accepted the debugging connection within 45s". Chrome is waiting for you to click Allow. Click it and call the tool again; the pending connection is kept, so no second dialog appears.
The server was restarted while the Allow dialog was open. Chrome keeps that dialog even though nothing is waiting on it. Close it with Deny or ×; clicking Allow does nothing for the new server process, which shows its own.
"refused the debugging connection (HTTP 403)". You clicked Deny, or debugging is off. Enable it in
chrome://inspect/#remote-debuggingand call the tool again; that call opens a new Allow dialog — click it.The connection dropped mid-work (Chrome restarted, debugging toggled). The next tool call reconnects and Chrome shows one new Allow dialog.
For a Chrome on another machine add SSH_PROXY_TO (e.g. user@remote) and,
if needed, CHROME_USER_DATA_DIR for the remote profile. The server reads
DevToolsActivePort over ssh and opens the ssh -L forward itself, on
demand; the Allow dialog appears on the remote Chrome.
Do not set CDP_URL or CHROME_LAUNCH together with CHROME_AUTOCONNECT —
the server refuses to start.
SSH tunnel (optional)
To control a Chrome that only listens on a remote host's loopback, set:
Env var | Default | Meaning |
|
| Chrome endpoint. With a tunnel active, the remote-side address to forward to. |
| unset | SSH target, e.g. |
| unset | Fixed local port. Auto-assigned when unset. |
The server runs ssh -N -L 127.0.0.1:<local>:<host>:<port> <target> and points
CDP at the forwarded port. Requires key-based SSH auth (BatchMode=yes) and the
ssh client on PATH. The tunnel uses StrictHostKeyChecking=accept-new
(trust-on-first-use: unknown host keys are accepted automatically on first
connect).
Develop
uv sync # venv + runtime + dev group
pytest -qLocally, from a checkout (no publish needed):
uvx --from . chrome-remote-debugging-mcp
# or
python -m chrome_remote_debugging_mcpAvailable Tools
10 toolsbrowseA
Open url and return a readable view of the page, with numbered refs.
The view is built from Chrome's accessibility tree — what a screen reader
would announce — not from HTML, so it is compact enough to act on. Every
interactive element gets a #N ref usable with browse_act.
Opens a new tab when tab_id is omitted; pass the returned tab_id to
browse_act / browse_view. Returns
{"tab_id", "url", "view", "refs"} or {"error": ...}.
Inputs: url (required), tab_id.
browse_actA
Run several actions against the current view, then return one new view.
Each action is a dict with a do key:
{"do": "click", "ref": 3}{"do": "type", "ref": 2, "text": "коты", "clear": false}{"do": "press", "key": "Enter"}{"do": "select", "ref": 5, "value": "два"}{"do": "check", "ref": 9}/{"do": "uncheck", "ref": 9}{"do": "scroll", "ref": 7}or{"do": "scroll", "to": "bottom"}{"do": "hover", "ref": 4}{"do": "wait_for", "text": "Результаты", "timeout": 5}or{"do": "wait_for", "ref_gone": 3}
Refs come from the most recent browse or browse_view on this tab and
are invalid afterwards. The batch stops at the first failure; a view is
returned either way so you can see where the page ended up.
Returns {"tab_id", "steps", "view", "refs"}, plus "error" when a
step failed, or {"error": ...} when the tab could not be resolved.
Inputs: tab_id (required), actions_list (required).
browse_viewA
Re-read the current page and return a fresh view with fresh refs.
Refs from an earlier view stop being valid once this returns. Returns
{"tab_id", "view", "refs"} or {"error": ...}.
Inputs: tab_id (required).
cdp_commandA
Send a raw CDP command and return its raw result — escape hatch.
Use when the higher-level tools don't cover what you need. method is any
CDP method (e.g. "Page.captureScreenshot", "DOM.getDocument",
"Network.enable"); params are its parameters. Runs in the given
tab's persistent session, so objectId/nodeId values and domain
state (e.g. Network.enable) carry over between calls while the tab is
open and the connection lives.
Events are not delivered. So Fetch.enable, Debugger.pause,
Target.setAutoAttach {waitForDebuggerOnStart: true} and
Page.setInterceptFileChooserDialog {enabled: true} hang the tab until
undone (Fetch.disable, Debugger.resume,
…{waitForDebuggerOnStart: false}, …{enabled: false}) or the tab is
closed. Browser.* and Target.* are not supported; their results
are undefined. Returns {"tab_id", "method", "result"} or
{"error": ...}.
Inputs: method (required), tab_id (required), params.
close_tabA
Close a Chrome tab opened earlier (e.g. by browse / navigate).
Its refs are dropped along with it. Returns {"tab_id", "closed": True}
or {"error": ...}.
Inputs: tab_id (required).
evaluateA
Evaluate a short JavaScript expression in a Chrome tab.
Only for small snippets (a few lines): for a longer script, write it to a
file and run it with evaluate_file instead. Awaits promises and
returns the value by value. Returns {"tab_id", "value", "type"} on
success, or {"error": ...} on failure or an uncaught JS exception.
A promise that does not settle within 30 s is reported as an error.
For a large value (e.g. a page's text) pass output_path: an absolute
path (~ is expanded) on the machine running this server. The value is
written there instead of returned — a string as is (UTF-8), anything else
as indented JSON — overwriting any existing file, and the result is
{"tab_id", "path", "type", "bytes"}. On an error the file is not written.
Inputs: tab_id (required), expression (required), output_path.
evaluate_fileA
Evaluate a JavaScript file in a Chrome tab — evaluate for big scripts.
path must be absolute (~ is expanded) and names a UTF-8 file on the
machine running this server, not the one running Chrome. Its contents run
exactly as an evaluate expression: the value of the last statement is
returned, promises are awaited (30 s limit), and stack traces of a JS
exception name the file. Returns {"tab_id", "value", "type"} or
{"error": ...}. output_path saves the value to a file instead,
exactly as in evaluate.
Inputs: path (required), tab_id (required), output_path.
list_tabsA
List open Chrome page tabs.
Returns {"tabs": [{id, title, url, type}, ...]} or {"error": ...}
if Chrome is unreachable.
Inputs: no named parameters.
pingA
Check connectivity to Chrome's DevTools endpoint (CDP_URL, or the
autoConnect source with CHROME_AUTOCONNECT).
Returns {"connected": True, "cdp_url", "browser", "protocol"} when
Chrome answers, or {"connected": False, "cdp_url", "error": ...} when it
is unreachable.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Most tools serve clearly distinct purposes: tab lifecycle, JS evaluation, accessibility browsing, and raw CDP are separable. The main overlap is navigate versus browse, both of which can open/navigate a tab, and evaluate versus evaluate_file differ mainly by input size, though descriptions make those distinctions reasonably clear.
Names are consistently snake_case and mostly use recognizable verbs: list_tabs, navigate, evaluate, browse, close_tab, etc. The browse_* family is coherent, while cdp_command and ping are minor deviations from a strict verb_noun pattern but remain readable and conventional for this domain.
Ten tools is well-scoped for a Chrome DevTools MCP server. Each tool covers a meaningful capability area—connectivity, tab management, JS execution, raw CDP escape hatch, and structured browsing—without obvious redundancy.
The surface covers tab listing, opening/navigation, closing, JS evaluation, accessibility-tree browsing, page actions, and raw CDP commands, which is strong lifecycle coverage. Minor high-level gaps remain, such as screenshots or direct DOM queries without falling back to cdp_command, but these are workable via the escape hatch.
Maintenance
Related MCP Connectors
Unofficial Browserless MCP — wraps the Browserless headless-Chromium REST API (browserless.io)
Hosted real Google Chrome MCP with per-user persistent state. Navigate, click, type, screenshot.
Browser MCP for logged-in tasks. Uses your Chrome — credentials stay local. Zero-token replay.
Official Browserless MCP server: browser automation, scraping, screenshots and PDFs for AI agents.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables direct browser control via Chrome DevTools Protocol, supporting navigation, interaction, content extraction, and screenshots through a single MCP tool.1374MIT
- AlicenseAqualityBmaintenanceAn MCP server that connects AI agents to a running Chrome tab via the Chrome DevTools Protocol (CDP), enabling runtime debugging and page inspection.2556 npm1ISC
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients to drive individually named Chrome profiles, providing tools for tabs, navigation, page interaction, screenshots, JavaScript evaluation, console logs, and network inspection over stdio without a TCP port.MIT
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to drive a live Chrome or Brave browser over stdio, with tools for navigation, clicking, typing, screenshots, and executing automation goals.4MIT