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
Made with ☕ by null-runner