nodriver-mcp-server

Overview Schema Source Related Servers Discussions Admin

Attach to a running browser

use_running_browser

DestructiveIdempotent

Attach to an already running Chrome to control your signed-in browser session without launching a new instance. Preserves real logins by connecting to the existing process.

Instructions

Drive a Chrome that is already running, instead of launching a new one.

This is how you use a browser you are already signed into. Chrome locks its user-data-dir, so the profile holding your real logins cannot be opened a second time — attaching to the running instance is the only way in, and it saves rebuilding every login through the automation.

The user starts Chrome themselves, once:

chrome --remote-debugging-port=9222 --user-data-dir=/path/to/profile

then this tool attaches to it. Every tool then acts on that browser and its real tabs.

--user-data-dir is not optional, and it must not be Chrome's own default directory. Since Chrome 136 the port is refused there — Chrome starts normally, says nothing, and nothing ever listens, which is a confusing way to fail. So the everyday profile cannot be reached by adding the flag to it; it has to be a directory of its own, and a copy of an existing profile is accepted (--profile-directory then picks which profile inside it).

SECURITY: that profile becomes part of the agent's reach. Whatever it is signed into — mail, bank, company systems — is reachable from here, because a cookie jar is all or nothing. Point this at a profile you are willing to expose, not your everyday one.

While attached, close_browser and every profile switch only detach; they never close a browser they did not start. Return to a self-launched browser with use_temp_profile or use_profile.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`host`	No	Host the browser is listening on. Leave at 127.0.0.1 unless you are attaching to a browser on another machine or in a container.	127.0.0.1
`port`	No	The remote debugging port Chrome was started with, e.g. 9222 for --remote-debugging-port=9222.
`browser`	No	Which browser to act on. Each name is an independent Chrome, created on first use. Omit for the shared default; parallel agents each need their own name.	default

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv2.5.0Sep 25, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Despite annotations already flagging destructiveHint=true and idempotentHint=true, the description adds critical behavioral context: close_browser and profile switches only detach and never close a browser they did not start, and the attached browser becomes part of the agent's reach with all-or-nothing cookie access. It also explains a common failure mode (port refused without --user-data-dir) and the security risk of exposing a profile.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-structured, with clear sections (SECURITY) and a logical flow. It front-loads the core purpose and then expands into prerequisites, security implications, and detach behavior. Every sentence contributes essential context for correct use, though it could be tightened without losing critical information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex tool that attaches to an external browser, the description covers everything an agent needs: the setup command, the user-data-dir requirement and its caveats, security warnings, behavior of related tools (close_browser, profile switches), and how to return to self-launched browsers. With an output schema present, no return-value details are missing. This is complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% — all three parameters have detailed descriptions covering host, port, and browser. The tool description adds minimal parameter-specific information beyond what the schema already provides (e.g., it mentions the default port but the schema does too). Since the schema does the heavy lifting, a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('Drive a Chrome that is already running') and clearly differentiates it from alternatives like use_temp_profile or use_profile. It explains the exact scenario (signed-in browser) and why this tool is the only way in, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use the tool ('a browser you are already signed into'), explains the underlying reason (Chrome locks the user-data-dir), and gives concrete prerequisites (the user must start Chrome with --remote-debugging-port and --user-data-dir). It also names the alternatives for returning to a self-launched browser, providing clear routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server