Cherry Chrome MCP
CSS selector-based Chrome DevTools MCP server with full JavaScript debugger support.
Features
- CSS Selector-based: Query and interact using familiar CSS selectors
- Powerful Filtering: Text content and visibility filters for precise element selection
- Rich Element Details: HTML snippets, structure summaries, and interactive element lists
- Compact Results: Returns only what you query, not entire page snapshots
- Multi-Instance Support: Connect to multiple Chrome instances simultaneously
- Full Debugger: Breakpoints, stepping, call stack inspection, expression evaluation
- Result Limit Controls: Default 5 elements, max 20 per query to keep responses focused
- Smart Tools Mode: NEW! Consolidated action-based tools with dynamic visibility and auto-bundled context
- Built on Puppeteer: Same battle-tested foundation as official Chrome DevTools MCP
- TypeScript: Type-safe, ported from Python chrome-debugger-mcp
Installation
npm install
npm run build
Usage
Quick Start with npx
Run directly from GitHub without cloning:
# Legacy mode (23 granular tools)
npx github:brandon-fryslie/cherry-chrome-mcp
# Smart mode (19 consolidated tools with dynamic visibility)
USE_SMART_TOOLS=true npx github:brandon-fryslie/cherry-chrome-mcp
As MCP Server
Add to your MCP client configuration:
{
"mcpServers": {
"cherry-chrome": {
"command": "npx",
"args": ["github:brandon-fryslie/cherry-chrome-mcp"],
"env": {
"USE_SMART_TOOLS": "true"
}
}
}
}
Development
npm run dev # Watch mode
npm run build # Build
npm test # Run tests
npm start # Build and start
Testing with MCP Inspector
# Legacy mode (23 granular tools)
npx @modelcontextprotocol/inspector node build/src/index.js
# Smart mode (19 consolidated tools with dynamic visibility)
USE_SMART_TOOLS=true npx @modelcontextprotocol/inspector node build/src/index.js
Tool Modes
Cherry Chrome MCP supports two tool modes via the USE_SMART_TOOLS environment variable:
Legacy Mode (default)
23 granular tools with explicit names for each action. See "Available Tools" section below.
Smart Mode (NEW!)
19 consolidated action-based tools with three major improvements:
1. Consolidated Tools - Related actions combined into single tools:
chrome(action: "connect" | "launch") - Replaces chrome_connect + chrome_launch
target(action: "list" | "switch") - Replaces list_targets + switch_target
step(direction: "over" | "into" | "out") - Replaces 3 step tools
execution(action: "resume" | "pause") - Replaces debugger_resume + debugger_pause
breakpoint(action: "set" | "remove") - Replaces set + remove breakpoint
2. Dynamic Tool Visibility - Tools appear/disappear based on connection state:
- Not connected: 2 tools (chrome, chrome_list_connections)
- Connected: 12 tools (adds DOM + target + utilities)
- Debug enabled: 15 tools (adds debugger tools)
- Paused: 5 tools (step, execution, evaluate, call_stack, show_tools)
Reduces context overhead by hiding irrelevant tools automatically.
3. Smart Auto-Bundled Responses - Tools include contextual information by default:
- Pause/breakpoint: Auto-includes call stack, local variables (top 10), console logs (last 3)
- Step: Auto-includes new location, variables with [CHANGED] markers, new console output
- Navigate: Auto-includes page title, console errors, element summary
- Click/fill: Auto-includes triggered console logs, element state
Eliminates follow-up tool calls by anticipating what information you'll need next.
All smart tools support include_context: false to disable auto-bundling if needed.
Available Tools
Legacy Mode (23 tools)
Chrome Connection Management (5 tools)
chrome_connect(port, connection_id, host) - Connect to existing Chrome
chrome_launch(debug_port, headless, user_data_dir, extra_args, connection_id) - Launch new Chrome
chrome_list_connections() - List all active connections
chrome_switch_connection(connection_id) - Switch active connection
chrome_disconnect(connection_id) - Disconnect from Chrome instance
Target Management (2 tools)
list_targets(connection_id) - List all pages/workers
switch_target(connection_id, index, title, url) - Switch to different page