Chrometools Mcp

chrometools-mcp

> 🌐 [Русская версия README](./README.ru.md)

AI-powered Chrome automation through natural language. No more fighting with CSS selectors, XPath expressions, or brittle test scripts. Just tell your AI assistant what you want to do on a web page, and ChromeTools MCP makes it happen.

Why ChromeTools MCP?

For AI Agents & Developers:

• 🎯 56+ specialized tools for browser automation - from simple clicks to Figma comparisons
• 🧠 APOM (Agent Page Object Model) - AI-friendly page representation (~8-10k tokens vs 5-10k for screenshots)
• 🔄 Persistent browser sessions - pages stay open between commands for iterative workflows
• ⚡ Framework-aware - handles React, Vue, Angular events and state updates automatically
• 📸 Visual testing - compare designs pixel-by-pixel with Figma integration
• 🎬 Scenario recording - record browser actions, replay them, or export as Playwright/Selenium tests
• 🌍 Cross-platform - works seamlessly on Windows, WSL, Linux, and macOS

Perfect for:

• 🤖 Building AI agents that interact with web applications
• 🧪 Automated testing without writing code - let AI generate tests from scenarios
• 🔍 Web scraping and data extraction with natural language instructions
• 🎨 Design validation - compare implemented UI with Figma designs
• 🚀 Rapid prototyping - test user flows by describing them to AI
• 📊 Monitoring and health checks for web applications

Stop writing brittle automation scripts. Start describing what you want in plain English.

Installation

Claude Code (CLI)

The easiest way to install for Claude Code users:

claude mcp add chrometools -- npx chrometools-mcp

This command will automatically configure the MCP server in your Claude Code settings.

Claude Desktop

Add to your Claude Desktop configuration file:

macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "chrometools": {
      "command": "npx",
      "args": ["chrometools-mcp"]
    }
  }
}

Cursor

Step 1: Open MCP Settings in Cursor

• Click on Settings (⚙️ icon or Cmd + , / Ctrl + ,)
• Navigate to Cursor Settings → MCP

Step 2: Edit MCP Configuration

• You'll see the MCP configuration JSON editor
• Add chrometools to the mcpServers object:

{
  "mcpServers": {
    "chrometools": {
      "command": "npx",
      "args": ["chrometools-mcp"]
    }
  }
}

If you already have other MCP servers configured, just add chrometools to the existing list:

{
  "mcpServers": {
    "existing-server": {
      "command": "npx",
      "args": ["some-other-mcp"]
    },
    "chrometools": {
      "command": "npx",
      "args": ["chrometools-mcp"]
    }
  }
}

Step 3: Save and Restart

• Save the configuration file
• Restart Cursor to apply changes
• The chrometools-mcp tools will now be available in Cursor Agent

Step 4: Test the Installation

• Open Cursor Chat
• Select Agent mode
• Try a command like: "Open browser and navigate to google.com"

Google Antigravity

Step 1: Open Agent session in Antigravity

Step 2: Click the "…" dropdown at the top of the editor's side panel

Step 3: Select "MCP Servers" to open the MCP Store

Step 4: Click "Manage MCP Servers" at the top of the MCP Store

Step 5: Click "View raw config" in the main tab

Step 6: Edit mcp_config.json (located in ~/.gemini/antigravity/ directory):

{
  "mcpServers": {
    "chrometools": {
      "command": "npx",
      "args": ["chrometools-mcp"]
    }
  }
}

Step 7: Save the file and restart Antigravity

Note: Antigravity has a limit of ~100 tools per session. If you have many MCP servers installed, consider reducing the number of active tools to ~25 for optimal performance.

Other MCP Clients

For Cline, Continue, or other MCP-compatible clients, add to your MCP configuration:

{
  "mcpServers": {
    "chrometools": {
      "command": "npx",
      "args": ["chrometools-mcp"]
    }
  }
}

Manual Installation

You can also run directly without configuration:

npx chrometools-mcp

Chrome Extension Setup

The Chrome Extension is required for scenario recording and other advanced features. Follow these steps to install it:

Important: ChromeTools opens Chrome with a separate user profile, so you must install the extension after ChromeTools starts Chrome for the first time.

Step 1: Start ChromeTools MCP server first

• Make sure ChromeTools is running through your MCP client (Claude Desktop, Cursor, etc.)
• Or run it manually: npx chrometools-mcp
• This will launch Chrome with ChromeTools' isolated profile

Step 2: Enable Developer Mode in Chrome

• Open Chrome Extensions page: chrome://extensions
• Toggle Developer mode (switch in top-right corner)

Step 3: Download and Extract the Extension

Option A - Download from GitHub (Recommended):

1. Download the extension archive: chrome-extension.zip
2. Extract the ZIP file to a folder on your computer
3. Remember the extraction path (you'll need it in the next step)

Option B - Use from node_modules (if you know the path):

• After npx install: ~/.npm/_npx/.../node_modules/chrometools-mcp/extension
• After global install: /node_modules/chrometools-mcp/extension
• From source: /extension

Step 4: Load the Extension

• Click "Load unpacked" button
• Navigate to the extracted extension folder (from Step 3)
• Select the folder and click "Select Folder"

Step 5: Verify Installation

• You should see "ChromeTools MCP" extension appear in your extensions list with:
• Name: ChromeTools MCP
• Version: (current version)
• Description: MCP server integration for Chrome automation
• Status: Toggle should be ON (blue)
• Look for the ChromeTools icon (CT) in your Chrome toolbar
• The extension is now ready to use for scenario recording

> Note: After installation, the extension card will appear on the chrome://extensions page alongside other installed extensions. The extension should show as "Enabled" with a blue toggle switch.

Step 6: Pin the Extension (Optional but Recommended)

• Click the puzzle piece icon in Chrome toolbar
• Find "ChromeTools MCP" in the list
• Click the pin icon to keep it visible in toolbar

Troubleshooting:

• Recommended: Use Option A (download from GitHub) to avoid searching in node_modules
• If using Option B and can't find the extension folder after npx install, run npm list -g chrometools-mcp to find the installation path
• The extension only works with Chrome instances launched by ChromeTools
• If Chrome closes and reopens, the extension should still be loaded (developer mode persists)
• When ChromeTools first opens Chrome, it automatically shows a prompt with the extension path in node_modules

Table of Contents

• [Installation](#installation)
• [Chrome Extension Setup](#chrome-extension-setup)
• [AI Optimization Features](#ai-optimization-features)- [Scenario Recorder](#scenario-recorder) - Visual UI-based recording with smart optimization
• [Available Tools](#available-tools) - 51+ Tools Total
• [AI-Powered Tools](#ai-powered-tools) - smartFindElement, analyzePage, getElementDetails, findElementsByText
• [Core Tools](#1-core-tools) - ping, openBrowser
• [Interaction Tools](#2-interaction-tools) - click, type, scrollTo, selectOption, selectFromGroup, drag, scrollHorizontal
• [Inspection Tools](#3-inspection-tools) - getElement, getComputedCss, getBoxModel, screenshot
• [Advanced Tools](#4-advanced-tools) - executeScript, getConsoleLogs, listNetworkRequests, getNetworkRequest, filterNetworkRequests, hover, pressKey, setStyles, setViewport, getViewport, navigateTo
• [Tab Management Tools](#5-tab-management-tools) - listTabs, switchTab
• [Frame Tools](#5a-frame-tools-iframe-automation) - listFrames, switchFrame (cross-origin iframe automation)
• [Recorder Tools](#7-recorder-tools) - enableRecorder, executeScenario, listScenarios, searchScenarios, getScenarioInfo, deleteScenario, exportScenarioAsCode, appendScenarioToFile, generatePageObject
• [API / Swagger Tools](#8-api--swagger-tools) - loadSwagger, generateApiModels
• [Typical Workflow Example](#typical-workflow-example)
• [Tool Usage Tips](#tool-usage-tips)
• [Configuration](#configuration)
• [Multi-Instance Support](#multi-instance-support) - Run multiple MCP servers simultaneously
• [WSL Setup Guide](#wsl-setup-guide) → [Full WSL Guide](WSL_SETUP.md)
• [Development](#development)
• [Features](#features)
• [Architecture](#architecture)

AI Optimization Features

: Dramatically reduce AI agent request cycles with intelligent element finding and page analysis.

Why This Matters

Traditional browser automation with AI requires many trial-and-error cycles:

AI: "Find login button"
→ Try selector #1: Not found
→ Try selector #2: Not found
→ Try selector #3: Found! (3 requests, 15-30 seconds)

With AI optimization:

AI: smartFindElement("login button")
→ Returns ranked candidates with confidence scores (1 request, 2 seconds)

Key Features

1. analyzePage - 🔥 USE FREQUENTLY - Get current page state after loads, clicks, submissions (cached, use refresh:true)
2. smartFindElement - Natural language element search with multilingual support
3. AI Hints - Automatic context in all tools (page type, page heading, modal content, dropdown/menu items, suggestions)
4. Text search - findElementsByText for finding elements by visible text

Performance: 3-5x faster, 5-10x fewer requests

Best Practice:

• Use analyzePage() after page loads AND after interactions (clicks, submissions)
• Use analyzePage({ refresh: true }) after page changes to see current state
• Prefer analyzePage over screenshot for debugging form data

📚 [Full AI Optimization Guide](AI_OPTIMIZATION.md)

Scenario Recorder

: Visual UI-based recorder for creating reusable test scenarios with automatic secret detection.

Features

• Visual Widget - Floating recorder UI with compact mode (50x50px minimize button)
• Auto-Reinjection - Recorder persists across page reloads/navigation automatically with duplicate prevention - Smart Click Detection - Finds actual clickable parent elements with event listeners- Smart Waiters - 2s minimum + animation/network/DOM change detection after clicks- Detailed Error Reports - Comprehensive failure analysis with context and suggestions- Smart Recording - Captures clicks, typing, navigation with intelligent optimization
• Secret Detection - Auto-detects passwords/emails and stores them securely
• Action Optimization - Combines sequential actions, removes duplicates
• Scenario Management - Save, load, execute, search, and delete scenarios
• Dependencies - Chain scenarios together with dependency resolution
• Multi-Instance Protection - Prevents multiple recorder instances from interfering

Quick Start

// 1. Enable recorder UI
enableRecorder()

// 2. Click "Start" in widget, perform actions, click "Stop & Save"
// 3. Execute saved scenario
executeScenario({ name: "login_flow", parameters: { email: "user@test.com" } })

📚 [Full Recorder Guide](RECORDERQUICKSTART.md) | [Recorder Spec](RECORDERSPEC.md)

Available Tools

⚠️ Tool Usage Priority

CRITICAL: Always use specialized tools first. Never jump to executeScript as first choice.

For Clicking/Interaction

1. ✅ click() - PRIMARY tool for all clicks

• Works correctly with React/Vue/Angular synthetic events
• Handles button clicks, link navigation, form submissions

1. ✅ findElementsByText() + action - When selector is unknown, find by text
2. ⚠️ executeScript() - LAST RESORT, only if above failed

For Filling Forms

1. ✅ type() - PRIMARY tool for all text input

• Properly updates React hooks, Vue reactive data
• Auto-clears field before typing (configurable)

1. ⚠️ executeScript() - LAST RESORT, only if above failed

For Reading Page State

1. ✅ analyzePage() - PRIMARY tool for reading page content

• Gets forms, inputs, buttons, links with current values
• Use refresh: true after interactions to see updated state
• Efficient: 2-5k tokens vs screenshot 5-10k

1. ✅ findElementsByText() - Find specific elements by visible text
2. ✅ getElement() - Get HTML of specific element
3. ⚠️ executeScript() - LAST RESORT, only if above failed

Model-Based Interaction (Advanced)

1. ✅ executeModelAction() - Universal tool for model-specific actions

• Works with element models (Strategy Pattern)
• Supports both APOM ID and CSS selector
• Framework-specific actions (e.g., DatePicker SetDate, Checkbox toggle)
• Example: executeModelAction({id: "input_34", action: "check"})
• Example: executeModelAction({selector: ".datepicker", action: "SetDate", params: {date: "2024-03-15"}})
• See models/ directory for available models and actions
• Available models: TxtInp, Sel, Btn, Chk, Radio, TxtArea, Link, Range, DatePicker, DateInp, FileInp, ColorInp, Modal, default

Modal/Dialog Support

• Automatic detection: APOM detects modals rendered via React Portals (antd, MUI, Bootstrap, Chakra, Mantine, Element UI, Headless UI, Radix)
• Detection methods: role="dialog", aria-modal="true", framework-specific CSS classes
• Animation-proof: Modal elements are included even during CSS appear animations (opacity: 0)
• Rich metadata: Modal nodes include title and actions (button labels) in metadata
• In APOM tree: Modals appear as type: "dialog" with model: "Modal", containing all interactive children

Why specialized tools matter:

• ✅ Trigger proper browser events (click, input, change)
• ✅ Work with React/Vue/Angular synthetic event systems
• ✅ Update framework state correctly (React hooks, Vue reactivity)
• ✅ Handle animations, navigation, and async updates
• ❌ executeScript bypasses framework events and may fail silently

AI-Powered Tools

smartFindElementFind elements using natural language descriptions instead of CSS selectors.

• Parameters:
• description (required): Natural language (e.g., "login button", "email field")
• maxResults (optional): Max candidates to return (default: 5)
• minConfidence (optional): Confidence threshold (0–1, default 0.6) for auto-executing action. If the best match scores below this — or is too close to the runner-up — the action is skipped and candidates are returned with an actionSkipped reason instead. Prevents auto-clicking the wrong control (e.g. a primary form submit when you asked for a menu item). Lower it to act on weaker matches.
• Candidate coverage: besides button/input/a/[role=button], also considers [onclick], [role=menuitem], [role=tab], and links inside nav/[role=navigation]/[role=menu] — so menu items rendered as div/span[onclick] are found. Scoring penalizes candidates whose text doesn't match the description and rewards navigation/menu context.
• Use case: When you don't know the exact selector
• Returns: Ranked candidates with confidence scores, selectors, and reasoning
• Example:

``json { "description": "submit button", "maxResults": 3 } ` Returns: `json { "candidates": [ { "selector": "button.login-btn", "confidence": 0.95, "text": "Login", "reason": "type=submit, in form, matching keyword" }, { "selector": "#submit", "confidence": 0.7, "text": "Send", "reason": "submit class" } ], "hints": { "suggestion": "Use selector: button.login-btn" } } ``

analy

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: docentovich
• Source: docentovich/chrometools-mcp
• License: ISC

Install and usage instructions live in the source repository linked above.