Chrome Devtools

Chrome DevTools MCP Skill

Control Chrome browser programmatically via chrome-devtools-mcp.

⚡ Performance Tip: Always use the patterns in "Quick Start" section below. They include cleanup and run everything in ONE command to avoid browser lock issues.

Speed Comparison:

• ❌ OLD WAY: Multiple attempts, manual cleanup, 5-10 commands → ~60-90 seconds
• ✅ NEW WAY: One optimized command → ~5-10 seconds

📚 See also: MCP CLI Guide for general MCP CLI patterns and best practices

Setup

# macOS
brew tap f/mcptools
brew install mcp

# Windows/Linux
go install github.com/f/mcptools/cmd/mcptools@latest

Quick Start (FASTEST)

Check Console Errors on localhost

Single command (copy-paste ready):

pkill -9 -f "chrome-devtools-mcp" 2>/dev/null; sleep 1; echo -e 'navigate_page {"url":"http://localhost:3000"}\nlist_console_messages {"pageIdx":0}\nexit' | timeout 30 mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated

Full Debug: Console + Network + Page Content

pkill -9 -f "chrome-devtools-mcp" 2>/dev/null; sleep 1; echo -e 'navigate_page {"url":"http://localhost:3000"}\nlist_console_messages {"pageIdx":0}\nlist_network_requests {"pageIdx":0}\ntake_snapshot {"verbose":true}\nexit' | timeout 30 mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated

Screenshot a Page

pkill -9 -f "chrome-devtools-mcp" 2>/dev/null; sleep 1; echo -e 'navigate_page {"url":"https://example.com"}\ntake_screenshot {"fullPage":true,"format":"png"}\nexit' | timeout 30 mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated

Execute JavaScript on Page

pkill -9 -f "chrome-devtools-mcp" 2>/dev/null; sleep 1; echo -e 'navigate_page {"url":"http://localhost:3000"}\nevaluate_script {"function":"() => document.querySelectorAll(\"div\").length"}\nexit' | timeout 30 mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated

⚡ Pattern: cleanup; sleep; echo commands | timeout shell

This avoids:

• ❌ Browser profile locks (cleanup first)
• ❌ Multiple shell sessions (one pipeline)
• ❌ Hanging commands (timeout wrapper)

Usage

List available tools:

mcp tools bunx -y chrome-devtools-mcp@latest

Call tools (individual commands):

# Navigate to a page (includes page list in response)
mcp call navigate_page bunx -y chrome-devtools-mcp@latest -- --isolated --params '{"url":"https://example.com"}'

# Take screenshot
mcp call take_screenshot bunx -y chrome-devtools-mcp@latest -- --isolated --params '{"fullPage":true,"format":"png"}'

# Take snapshot (page content as text)
mcp call take_snapshot bunx -y chrome-devtools-mcp@latest -- --isolated --params '{"verbose":false}'

# List console messages
mcp call list_console_messages bunx -y chrome-devtools-mcp@latest -- --isolated --params '{"pageIdx":0}'

# Execute JavaScript
mcp call evaluate_script bunx -y chrome-devtools-mcp@latest -- --isolated --params '{"function":"() => document.title"}'

Interactive shell mode (RECOMMENDED - maintains single browser instance):

mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated

# Then run commands:
navigate_page {"url":"https://example.com"}
take_snapshot {"verbose":false}
list_console_messages {"pageIdx":0}
new_page {"url":"https://httpbin.org"}
exit

With Chrome launch options:

# Headless mode
mcp call navigate_page bunx -y chrome-devtools-mcp@latest -- --headless --isolated --params '{"url":"https://example.com"}'

# Custom viewport
mcp call navigate_page bunx -y chrome-devtools-mcp@latest -- --viewport "1920x1080" --isolated --params '{"url":"https://example.com"}'

# Connect to existing Chrome instance (no --isolated needed)
mcp call navigate_page bunx -y chrome-devtools-mcp@latest -- --browserUrl http://127.0.0.1:9222 --params '{"url":"https://example.com"}'

Common Workflows

Check localhost console logs:

# Shell mode (RECOMMENDED):
mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated
# Then: navigate_page {"url":"http://localhost:3000"}
# Then: list_console_messages {"pageIdx":0}

# Or as individual commands:
mcp call navigate_page bunx -y chrome-devtools-mcp@latest -- --isolated --params '{"url":"http://localhost:3000"}'
mcp call list_console_messages bunx -y chrome-devtools-mcp@latest -- --isolated --params '{"pageIdx":0}'

Automate form filling:

mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated
# Then in shell:
# navigate_page {"url":"https://example.com/login"}
# take_snapshot {"verbose":false}   # Get UIDs for elements
# fill {"uid":"#username","value":"user"}
# fill {"uid":"#password","value":"pass"}
# click {"uid":"#submit"}

Network debugging:

# Shell mode (RECOMMENDED):
mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated
# Then: navigate_page {"url":"https://example.com"}
# Then: list_network_requests {"pageIdx":0}

# Or as individual commands:
mcp call navigate_page bunx -y chrome-devtools-mcp@latest -- --isolated --params '{"url":"https://example.com"}'
mcp call list_network_requests bunx -y chrome-devtools-mcp@latest -- --isolated --params '{"pageIdx":0}'

Key Tools

• navigate_page - Go to URL (returns page list)
• new_page - Open new tab (returns page list)
• select_page - Switch to different page by index
• close_page - Close page by index
• click - Click element
• fill - Fill input/textarea
• evaluate_script - Run JavaScript
• take_screenshot - Capture page as image
• take_snapshot - Get page content as text with UIDs
• list_console_messages - View console logs (use {"pageIdx":0})
• list_network_requests - View network activity (use {"pageIdx":0})
• wait_for - Wait for text/condition

Important Notes

• Always use bunx (not npx) for chrome-devtools-mcp
• Correct syntax: mcp call TOOL_NAME bunx -y chrome-devtools-mcp@latest -- --isolated --params '{...}'
• Server command comes AFTER tool name, BEFORE --params
• Parameters are passed directly (no "arguments" wrapper)
• Use -- --isolated to create temporary profile (prevents browser lock conflicts)
• Server exposes full browser content - avoid sensitive data

Working with Multiple Commands

Problem: Each mcp call starts a new server & browser instance, causing conflicts.

Solutions:

1. Shell mode (RECOMMENDED): Maintains single browser instance

   mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated

2. Individual calls: Use -- --isolated for one-off commands

   mcp call navigate_page bunx -y chrome-devtools-mcp@latest -- --isolated --params '{"url":"..."}'

3. Connect to running Chrome: Start Chrome with debugging enabled

   /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
   mcp call navigate_page bunx -y chrome-devtools-mcp@latest -- --browserUrl http://127.0.0.1:9222 --params '{"url":"..."}'

Known Issues (mcp CLI v0.7.1)

⚠️ Bug: Tools with empty parameter schemas fail with "Invalid arguments" error.

Workaround: Provide at least one optional parameter:

• ✅ list_console_messages {"pageIdx":0} - Works
• ✅ list_network_requests {"pageIdx":0} - Works
• ✅ take_snapshot {"verbose":false} - Works
• ❌ list_pages - Broken, use navigate_page or new_page instead (they return page list)

Troubleshooting

Problem: "The browser is already running" error

This happens when a previous Chrome instance is still holding the profile lock.

Quick fix (ALWAYS DO THIS FIRST):

pkill -9 -f "chrome-devtools-mcp" 2>/dev/null; sleep 1

Then run your command:

echo -e 'navigate_page {"url":"YOUR_URL"}\nlist_console_messages {"pageIdx":0}\nexit' | mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated

Problem: Multiple failed attempts

Don't create multiple shell sessions - keep ONE session open and run multiple commands:

❌ BAD (slow - 2 separate sessions):

echo 'navigate_page {"url":"..."}' | mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated
echo 'list_console_messages {"pageIdx":0}' | mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated

✅ GOOD (fast - 1 session, multiple commands):

echo -e 'navigate_page {"url":"..."}\nlist_console_messages {"pageIdx":0}\nexit' | mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated

Problem: Commands hanging/timing out

Use timeout to prevent hanging:

timeout 30 mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated

Chrome DevTools Skill Improvements

Performance Improvements

Before (from usage log)

• Multiple failed attempts with "browser already running" errors
• Had to manually kill processes 3-4 times
• Created separate shell sessions for each command
• Total execution time: ~60-90 seconds
• 8-10 separate Bash commands

After (optimized patterns)

• Single command with built-in cleanup
• No browser lock conflicts
• One shell session with multiple commands
• Total execution time: ~5-10 seconds
• 1 Bash command

Speed improvement: 6-9x faster ⚡

Key Changes

1. Added "Quick Start" Section

Ready-to-use commands for common tasks:

• Check console errors
• Full debug (console + network + snapshot)
• Take screenshots
• Execute JavaScript

2. Standardized Command Pattern

pkill -9 -f "chrome-devtools-mcp" 2>/dev/null; sleep 1; echo -e 'COMMANDS\nexit' | timeout 30 mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated

Components:

• pkill -9 -f "chrome-devtools-mcp" - Kill existing instances
• sleep 1 - Wait for cleanup
• echo -e 'COMMANDS\nexit' - Pipe multiple commands
• timeout 30 - Prevent hanging
• -- --isolated - Use temporary profile

3. Fixed Parameter Issues

• Removed incorrect {"arguments": {}} wrapper
• Added workarounds for empty parameter bug
• Documented that tools need at least one optional param

4. Added Troubleshooting Guide

• Browser lock conflicts → cleanup command
• Multiple failed attempts → use one session
• Commands hanging → use timeout

Testing Results

Test 1: Console + Network Check

pkill -9 -f "chrome-devtools-mcp" 2>/dev/null; sleep 1; echo -e 'navigate_page {"url":"https://httpbin.org/html"}\nlist_console_messages {"pageIdx":0}\nlist_network_requests {"pageIdx":0}\nexit' | timeout 30 mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated

✅ Result: Executed in ~8 seconds, returned:

• Page list
• Console messages (none found)
• Network requests (2 found)

Test 2: Page Snapshot

pkill -9 -f "chrome-devtools-mcp" 2>/dev/null; sleep 1; echo -e 'navigate_page {"url":"https://example.com"}\ntake_snapshot {"verbose":false}\nexit' | timeout 30 mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated

✅ Result: Executed in ~6 seconds, returned full page content with UIDs

Impact on Agent Performance

Old Workflow (from usage log)

1. Try navigate → browser lock error 2. Try shell mode → browser lock error 3. Check for processes 4. Kill process 7386 5. Kill process 7402 6. Try shell mode → works 7. Get console messages → success 8. Try network requests → browser lock error 9. Kill processes again 10. Try network requests → success

Total: 10+ steps, multiple failures

New Workflow

1. Run optimized command → success

Total: 1 step, no failures

Documentation Improvements

• Added performance comparison at top
• Quick start patterns for common use cases
• Single-line commands (no backslash continuations)
• Clear troubleshooting guide
• Emphasized shell mode over individual calls
• Added timeout recommendations