MCP tool. Single unified interface with auto-starting Chrome.
Announce:
"I'm using the browsing skill to control Chrome."
When to Use
Use this when:
Controlling authenticated sessions
Managing multiple tabs in running browser
Playwright MCP unavailable or excessive
Use Playwright MCP when:
Need fresh browser instances
Generating screenshots/PDFs
Prefer higher-level abstractions
Auto-Capture
Every DOM action (navigate, click, type, select, eval, keyboard_press) automatically saves:
{prefix}.png
— viewport screenshot
{prefix}.md
— page content as structured markdown
{prefix}.html
— full rendered DOM
{prefix}-console.txt
— browser console messages
Files are saved to the session directory with sequential prefixes (001-navigate, 002-click, etc.). You must check these before using extract or screenshot actions.
The use_browser Tool
Single MCP tool with action-based interface. Chrome auto-starts on first use.
Parameters:
action
(required): Operation to perform
tab_index
(optional): Tab to operate on (default: 0)
selector
(optional): CSS selector for element operations
payload
(optional): Action-specific data
timeout
(optional): Timeout in ms for await operations (default: 5000)
This clears cookies accessible to JavaScript. It won't clear:
httpOnly cookies (server-side only)
Cookies from other domains
For most logout/reset scenarios, this is sufficient.
Scroll Page
{action: "eval", payload: "window.scrollTo(0, document.body.scrollHeight); 'Scrolled to bottom'"}
{action: "eval", payload: "window.scrollTo(0, 0); 'Scrolled to top'"}
{action: "eval", payload: "document.querySelector('.target').scrollIntoView(); 'Scrolled to element'"}
Tips
Always wait before interaction:
Don't click or fill immediately after navigate - pages need time to load.
// BAD - might fail if page slow
{action: "navigate", payload: "https://example.com"}
{action: "click", selector: "button"} // May fail!
// GOOD - wait first
{action: "navigate", payload: "https://example.com"}
{action: "await_element", selector: "button"}
{action: "click", selector: "button"}
Use specific selectors:
Avoid generic selectors that match multiple elements.
// BAD - matches first button
{action: "click", selector: "button"}
// GOOD - specific
{action: "click", selector: "button[type=submit]"}
{action: "click", selector: "#login-button"}
Submit forms with \n:
Append newline to text to submit forms automatically.
{action: "type", selector: "#search", payload: "query\n"}
Check content first:
Extract page content to verify selectors before building workflow.
{action: "extract", payload: "html"}
Troubleshooting
Element not found:
Use
await_element
before interaction
Verify selector with
extract
action using 'html' format
Timeout errors:
Increase timeout:
{timeout: 30000}
for slow pages
Wait for specific element instead of text
Tab index out of range:
Use
list_tabs
to get current indices
Tab indices change when tabs close
eval returns
[object Object]
:
Use
JSON.stringify()
for complex objects:
{action: "eval", payload: "JSON.stringify({name: 'test'})"}
For async functions:
{action: "eval", payload: "JSON.stringify(await yourAsyncFunction())"}
Test Automation (Advanced)
When building test automation, you have two approaches:
Approach 1: use_browser MCP (Simple Tests)
Best for: Single-step tests, direct Claude control during conversation
{
"action"
:
"navigate"
,
"payload"
:
"https://app.com"
}
{
"action"
:
"click"
,
"selector"
:
"#test-button"
}
{
"action"
:
"eval"
,
"payload"
:
"JSON.stringify({passed: document.querySelector('.success') !== null})"
}
Approach 2: chrome-ws CLI (Complex Tests)
Best for: Multi-step test suites, standalone automation scripts
Key insight
:
chrome-ws
is the reference implementation showing proper Chrome DevTools Protocol usage. When
use_browser
doesn't work as expected, examine how
chrome-ws
handles the same operation.
Example: Automated form testing
./chrome-ws navigate
0
"https://app.com/form"
./chrome-ws fill
0
"#email"
"test@example.com"
./chrome-ws click
0
"button[type=submit]"
./chrome-ws wait-text
0
"Success"
When use_browser Fails
Check chrome-ws source code
- It shows the correct CDP pattern
Use chrome-ws to verify
- Test the same operation via CLI
Adapt the pattern
- Apply the working CDP approach to use_browser
Common Test Automation Patterns
Form validation
Fill forms, check error states
UI state testing
Click elements, verify DOM changes
Performance testing
Measure load times, capture metrics
Screenshot comparison
Capture before/after states
Advanced Usage
For command-line usage outside Claude Code, see
COMMANDLINE-USAGE.md
.
For detailed examples, see
EXAMPLES.md
.
Protocol Reference
Full CDP documentation:
https://chromedevtools.github.io/devtools-protocol/