Chrome MCP Docker

Persistent Chrome DevTools MCP Server

Stable, persistent Chrome DevTools for AI coding assistants.

Why Docker?

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

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