cherry-chrome

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