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 patterns and best practices (see create-mcp-skill skill for reference)

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:

Shell mode (RECOMMENDED): Maintains single browser instance

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

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

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

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