Chrome MCP Docker

Persistent Chrome DevTools MCP Server

Stable, persistent Chrome DevTools for AI coding assistants.

Why Docker?

| Feature | Official MCP | This | |---------|:------------:|:--------:| | Session Persistence | ❌ | ✅ | | Docker Stability | ❌ | ✅ | | Mobile Testing | ❌ | ✅ | | Native Interactions | ❌ | ✅ | | Console Logs | ❌ | ✅ | | Host Header Bypass | ❌ | ✅ |

Installation

Option A: Standalone (Recommended)

Works with just Docker - no additional dependencies.

# 1. Start Chrome container
docker run -d --name chrome-persistent --restart unless-stopped \
  -p 9222:9222 --shm-size=2g \
  zenika/alpine-chrome:with-puppeteer \
  --no-sandbox --remote-debugging-address=0.0.0.0 \
  --remote-debugging-port=9222 --disable-gpu --headless

# 2. Add to Claude Code (~/.claude.json)

{
  "mcpServers": {
    "chrome": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--network", "host",
               "-e", "CHROME_HOST=localhost", "-e", "CHROME_PORT=9222",
               "nullrunner/chrome-mcp-docker:latest"]
    }
  }
}

Option B: Docker MCP Gateway

Warning: The official Docker MCP Gateway has bugs affecting custom servers. See Known Issues. Use Option A or the patched fork below.

# Use patched fork (recommended if you want Gateway)
git clone https://github.com/null-runner/mcp-gateway.git
cd mcp-gateway && go build -o docker-mcp ./cmd/docker-mcp

# Then setup chrome-mcp-docker
git clone https://github.com/null-runner/chrome-mcp-docker.git
cd chrome-mcp-docker
./setup.sh

Tools

| Tool | What it does | |------|--------------| | navigate | Go to URL, wait for load | | screenshot | Capture viewport | | click | Click element | | type | Type into input | | scroll | Scroll page/element | | wait_for_selector | Wait for element | | get_computed_styles | CSS debugging | | get_network_errors | Failed requests | | get_console_logs | JS console output | | mobile_mode | iPhone X viewport |

Requirements

• Docker (one of):
  • Docker Desktop (Windows/Mac - easiest)
  • Docker Engine (Linux - see Setup Guide)
  • Podman (compatible alternative)
• Any MCP-compatible client (Claude Code, Cursor, Windsurf, Cline, etc.)

Documentation

• Setup Guide - Manual installation, configuration options
• Troubleshooting - Common issues and fixes
• Architecture - How it works under the hood

How It Works

AI Coding Assistant (Claude, Cursor, etc.)
    ↓
chrome-mcp-docker (MCP Server)
    ↓
Chrome DevTools Protocol
    ↓
Persistent Chrome Browser (Docker)

The key innovation: Host Header Bypass. Chrome rejects connections from Docker containers because host.docker.internal isn't localhost. This server spoofs the header.

Known Issues

Docker MCP Gateway has several open bugs affecting custom servers:

• PR #263 - Tool name prefix separator (: → __)
• PR #278 - Prefixed names sent to remote servers
• PR #279 - Claude clients excluded from tool activation

Recommendation: Use standalone installation (Option A) until these PRs are merged.

License

MIT

Report Bug · Request Feature

Made with ☕ by null-runner