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