# Chrome-Driver-MCP

**Repository Path**: sgs844575/chrome-driver-mcp

## Basic Information

- **Project Name**: Chrome-Driver-MCP
- **Description**: A Model Context Protocol (MCP) server for ChromeDriver browser automation. Built with Single Responsibility Principle (SRP) and Divide & Conquer architecture.
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-04-30
- **Last Updated**: 2026-05-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ChromeDriver MCP Server

A **Model Context Protocol (MCP)** server for ChromeDriver browser automation.
Built with **Single Responsibility Principle (SRP)** and **Divide & Conquer** architecture.

## Features

- **29 MCP Tools** covering complete browser automation workflow
- **Multi-transport support**: stdio (default), SSE, Streamable HTTP
- **Auto ChromeDriver management** via `webdriver-manager`
- **Structured logging** with `structlog`
- **Type-safe** Pydantic schemas for all inputs/outputs
- **Screenshot capture** with base64 encoding
- **JavaScript execution** in browser context
- **Console log collection** via Chrome DevTools Protocol

## Architecture

```
chrome_driver_mcp/
├── core/              # WebDriver lifecycle & browser options (SRP)
├── actions/           # Atomic browser operations (SRP per category)
│   ├── navigation.py
│   ├── interaction.py
│   ├── query.py
│   ├── screenshot.py
│   └── javascript.py
├── service/           # Business orchestration layer
├── mcp_layer/         # Protocol adaptation (FastMCP)
├── models/            # Pydantic schemas
├── config/            # Settings management
└── utils/             # Exceptions & logging
```

## Installation

```bash
# Using UV (recommended)
uv venv .venv
uv pip install -r requirements.txt

# Or using pip
pip install -r requirements.txt
```

## Quick Start

### STDIO Mode (default, for Claude Desktop)

```bash
python -m chrome_driver_mcp
```

### SSE Mode

```bash
python -m chrome_driver_mcp --transport sse --host 0.0.0.0 --port 8000
```

### Streamable HTTP Mode (recommended for production)

```bash
python -m chrome_driver_mcp --transport streamable-http --host 0.0.0.0 --port 8000
```

## Claude Desktop Configuration

Add to your Claude Desktop config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "chrome-driver": {
      "command": "python",
      "args": ["-m", "chrome_driver_mcp"],
      "env": {
        "CHROMEDRIVER_MCP_HEADLESS": "true",
        "CHROMEDRIVER_MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `CHROMEDRIVER_MCP_HEADLESS` | `true` | Run browser in headless mode |
| `CHROMEDRIVER_MCP_WINDOW_WIDTH` | `1920` | Browser window width |
| `CHROMEDRIVER_MCP_WINDOW_HEIGHT` | `1080` | Browser window height |
| `CHROMEDRIVER_MCP_USER_AGENT` | - | Custom user agent string |
| `CHROMEDRIVER_MCP_PROXY` | - | Proxy server URL |
| `CHROMEDRIVER_MCP_DISABLE_IMAGES` | `false` | Disable image loading |
| `CHROMEDRIVER_MCP_IMPLICIT_WAIT` | `10` | Implicit wait timeout (seconds) |
| `CHROMEDRIVER_MCP_PAGE_LOAD_TIMEOUT` | `30` | Page load timeout (seconds) |
| `CHROMEDRIVER_MCP_LOG_LEVEL` | `INFO` | Logging level |

## Available MCP Tools

### Navigation
- `browser_navigate` - Navigate to a URL
- `browser_go_back` - Go back in history
- `browser_go_forward` - Go forward in history
- `browser_refresh` - Refresh current page

### Element Interaction
- `browser_click` - Click an element
- `browser_input` - Type text into an element
- `browser_clear` - Clear input element
- `browser_hover` - Hover over an element

### Query
- `browser_find_element` - Find single element info
- `browser_find_elements` - Find multiple elements
- `browser_get_text` - Get element text
- `browser_get_attribute` - Get element attribute
- `browser_get_page_source` - Get full HTML
- `browser_get_current_url` - Get current URL
- `browser_get_title` - Get page title

### Screenshot
- `browser_screenshot` - Take screenshot (page/element/full-page)

### JavaScript
- `browser_execute_script` - Execute JavaScript

### Scroll & Wait
- `browser_scroll_to` - Scroll to element or position
- `browser_wait_for_element` - Wait for element condition

### Window
- `browser_set_window_size` - Set window dimensions

### Cookies
- `browser_get_cookies` - Get all cookies
- `browser_add_cookie` - Add a cookie
- `browser_delete_cookie` - Delete a cookie
- `browser_delete_all_cookies` - Delete all cookies

### Frames
- `browser_switch_to_frame` - Switch to iframe
- `browser_switch_to_default` - Switch to main document

### Console & Status
- `browser_get_console_logs` - Get browser console logs
- `browser_get_status` - Get browser status
- `browser_close` - Close browser instance

## Locator Format

All element-based tools accept a `locator` object:

```json
{
  "strategy": "css_selector",
  "value": "#submit-button"
}
```

Supported strategies: `id`, `xpath`, `css_selector`, `class_name`, `tag_name`, `name`, `link_text`, `partial_link_text`

## License

MIT