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