Chrome Control

Overview

Chrome Control is a powerful browser automation server that enables AI assistants and applications to control Chrome through a JSON-RPC interface, with special support for the Model Context Protocol (MCP). Built on Puppeteer with enhanced features for AI integration, it allows AI systems to navigate websites, interact with elements, capture screenshots, and extract structured data.

Key Benefits:

• 🧠 AI-Optimized: Designed specifically for AI assistants like Claude, GPT, and Bard
• 🛡️ Bot-Detection Avoidance: Stealth features to navigate modern websites without being blocked
• 🚀 Token Efficient: Customizable responses to minimize token usage in AI contexts
• 👁️ Visual Feedback: Option to run in windowed mode for users to see AI actions in real-time
• 🔄 Session Persistence: Support for user profiles to maintain login sessions and cookies

Website | Documentation | Examples

Quick Start

Installation

# Install globally
npm install -g mcp-chrome-control

# Or use without installation via npx
npx mcp-chrome-control

MCP Integration

Using NPX (Recommended for Production)

Add to your .mcp.json file:

{
  "chrome": {
    "type": "stdio",
    "command": "npx",
    "args": ["mcp-chrome-control"],
    "env": {}
  }
}

Using Local Installation (Recommended for Development)

For development, you can install the package globally and use the binary directly:

1. Link the package globally:

   git clone https://github.com/CodingButterBot/chrome-control.git
   cd chrome-control
   npm install
   npm link

2. Add to your .mcp.json file:

   {
     "chrome": {
       "type": "stdio",
       "command": "mcp-chrome-control",
       "args": [],
       "env": {}
     }
   }

Direct Client Usage

import { ChromeControlClient } from 'mcp-chrome-control/client';

async function runDemo() {
  const client = new ChromeControlClient();
  await client.start();
  
  // Create a browser (visible to user)
  const browserId = await client.createBrowser({ headless: false });
  
  // Navigate and interact
  await client.navigate('https://example.com', browserId);
  await client.screenshot(browserId, { path: 'screenshot.png' });
  
  // Clean up
  await client.closeBrowser(browserId);
  await client.stop();
}

Features

• Full Browser Automation: Navigation, clicking, form filling, keyboard/mouse control
• Visual Feedback: Run Chrome in windowed mode for users to see AI's actions
• DOM Filtering: Extract only relevant elements and attributes
• Screenshot Capabilities: Capture full-page or element-specific screenshots
• Anti-Detection Measures: Avoid bot detection through stealth techniques
• Session Persistence: Maintain login sessions and cookies between runs
• Action Chaining: Execute multiple browser operations in a single request
• Comprehensive Logging: Detailed logs for debugging and error tracking
• JavaScript Execution: Run custom JS in the browser context
• Context Persistence: Automatic tracking of browser and tab information across calls
• Robust Error Handling: Better error messages and recovery mechanisms
• Comprehensive Test Suite: Extensive tests covering all functionality

Core Tools

| Category | Tools | |----------|-------| | Browser Management | Create, list, and close browsers | | Navigation | Navigate to URLs with custom response formats | | Interaction | Click, hover, fill forms, select options | | Mouse & Keyboard | Direct control of mouse and keyboard actions | | Screenshots | Take full-page or element-specific screenshots | | JavaScript | Execute custom JavaScript in browser context |

View the complete tool reference →

Use Cases

• AI Web Research: Allow AI assistants to search and analyze web content
• Automated Testing: Script tests for websites and web applications
• Data Extraction: Scrape and structure web data for analysis
• Website Monitoring: Capture screenshots for visual monitoring
• Form Submission: Automate form filling and submission
• Visual Demonstrations: Show users how to perform actions on websites

Development & Contributing

We welcome contributions! Here's how to get started:

# Clone the repository
git clone https://github.com/CodingButterBot/chrome-control.git
cd chrome-control

# Install dependencies
npm install

# Start development server
npm run dev

# Run all tests
npm run test:all

# Run unit tests with pretty formatting
npm run test:units

# Run specific test categories
npm run test:nav          # Navigation tests
npm run test:form         # Form interaction tests  
npm run test:screenshot   # Screenshot and evaluation tests
npm run test:zod          # Zod schema conversion tests

# Test MCP tools directly with the MCP testing utility
npm run mcp:add chrome_create_browser '{}'
npm run mcp:run

MCP Testing Utility

For development and debugging, we provide a dedicated MCP testing utility that allows you to:

1. Create sequences of MCP tool calls in a JSON file
2. Execute them without needing an LLM integration
3. Test individual tool calls in isolation
4. Debug tool responses and context handling

To use it:

# Add a tool call to the sequence
npm run mcp:add chrome_navigate '{"url":"https://example.com"}'

# Execute the entire sequence
npm run mcp:run

This utility is particularly helpful for LLM developers who want to understand exactly how Chrome Control's MCP tools behave before integrating them with an AI system.

See our Contributing Guide for more details.

Resources

• Full Documentation
• Example Scripts
• API Reference
• Context Persistence
• Test Suite Documentation
• MCP Testing
• Changelog

License

MIT