Skip to content

Latest commit

 

History

History
204 lines (159 loc) · 5.05 KB

README.md

File metadata and controls

204 lines (159 loc) · 5.05 KB

Chrome MCP Server

Ultra-lightweight MCP server for Chrome DevTools Protocol via chrome-ws.

Features

  • Single Tool: use_browser with 13 actions
  • XPath & CSS: Selectors support both CSS and XPath (auto-detected)
  • Auto-start: Chrome launches automatically on first use
  • Zero Config: No setup required, works out of the box
  • Minimal Context: Streamlined descriptions reduce token usage
  • Direct Integration: Library-based (not subprocess) for speed and error handling

Installation

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "chrome": {
      "command": "node",
      "args": [
        "/path/to/using-chrome-directly/mcp/dist/index.js"
      ]
    }
  }
}

Other MCP Clients

The server uses stdio transport and works with any MCP client:

node /path/to/using-chrome-directly/mcp/dist/index.js

Usage

The use_browser tool accepts these parameters:

  • action (required): Action to perform (see Actions below)
  • tab_index (optional): Tab index to operate on (default: 0)
  • selector (optional): CSS or XPath selector (XPath must start with / or //)
  • payload (optional): Action-specific data
  • timeout (optional): Timeout in ms for await operations (default: 5000, max: 60000)

Actions

Action Description Required Parameters Payload
navigate Navigate to URL - URL string
click Click element selector -
type Type text (append \n to submit) selector Text string
extract Extract page content - Format: 'markdown' | 'text' | 'html'
screenshot Take screenshot - Filename string
eval Execute JavaScript - JavaScript code string
select Select dropdown option selector Option value(s)
attr Get element attribute selector Attribute name
await_element Wait for element selector -
await_text Wait for text - Text to wait for
new_tab Create new tab - -
close_tab Close tab - -
list_tabs List all tabs - -

Examples

Navigate to a page:

{
  "action": "navigate",
  "payload": "https://example.com"
}

Fill and submit a form:

{
  "action": "type",
  "selector": "#email",
  "payload": "user@example.com\n"
}

Extract page content as markdown:

{
  "action": "extract",
  "payload": "markdown"
}

Wait for element to appear:

{
  "action": "await_element",
  "selector": ".loaded-indicator",
  "timeout": 10000
}

Get link href:

{
  "action": "attr",
  "selector": "a.download",
  "payload": "href"
}

Extract with XPath:

{
  "action": "extract",
  "selector": "//h2 | //h3",
  "payload": "text"
}

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode (auto-rebuild)
npm run dev

Windows tip

Chrome is bound to 127.0.0.1:9222 by default to avoid hostname resolution issues on recent Windows builds. Override with CHROME_WS_HOST / CHROME_WS_PORT if you expose DevTools on a different interface.

Linux/WSL2 Headed Mode

The MCP server auto-detects display availability by checking the DISPLAY or WAYLAND_DISPLAY environment variables. When running in headed mode (visible browser window), Chrome needs these variables to connect to your display server.

Problem: In WSL2 or when MCP servers are spawned by applications that don't inherit your shell environment, these variables may not be set, causing show_browser to fail silently or Chrome to crash.

Solution: Explicitly configure the DISPLAY environment variable in your MCP server configuration:

{
  "mcpServers": {
    "chrome": {
      "command": "node",
      "args": ["/path/to/mcp/dist/index.js"],
      "env": {
        "DISPLAY": ":0"
      }
    }
  }
}

For Claude Code, add this to ~/.claude/mcp.json:

{
  "mcpServers": {
    "plugin_superpowers-chrome_chrome": {
      "command": "node",
      "args": ["${HOME}/.claude/plugins/cache/superpowers-marketplace/superpowers-chrome/VERSION/mcp/dist/index.js"],
      "env": {
        "DISPLAY": ":0"
      }
    }
  }
}

Replace VERSION with your installed version (e.g., 1.6.1).

Note: After updating the configuration, restart Claude Code or your MCP client for the changes to take effect.

Verifying your display: Run echo $DISPLAY in your terminal. Common values are :0 for WSLg or a local X server, or :10.0 for SSH X forwarding.

Architecture

mcp/
├── src/
│   └── index.ts       # MCP server with use_browser tool
├── dist/
│   └── index.js       # Compiled server (bundled with chrome-ws-lib)
├── package.json
└── tsconfig.json

The server imports chrome-ws-lib.js (located at ../skills/browsing/chrome-ws-lib.js) as a library and calls CDP functions directly, providing fast browser automation without subprocess overhead.

Credits

The implementation is based on an idea and prototype by Dan Grigsby.

License

MIT