<div align="center">
# Chrome MCP Docker
**Persistent Chrome DevTools MCP Server**
[](https://hub.docker.com/r/nullrunner/chrome-mcp-docker)
[](LICENSE)
[](https://modelcontextprotocol.io)
*Stable, persistent Chrome DevTools for AI coding assistants.*
</div>
---
## 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.
```bash
# 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)
```
```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](#known-issues). Use Option A or the patched fork below.
```bash
# 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](https://www.docker.com/products/docker-desktop/) (Windows/Mac - easiest)
- Docker Engine (Linux - see [Setup Guide](SETUP_GUIDE.md#advanced-running-without-docker-desktop))
- Podman (compatible alternative)
- Any MCP-compatible client (Claude Code, Cursor, Windsurf, Cline, etc.)
---
## Documentation
- [Setup Guide](SETUP_GUIDE.md) - Manual installation, configuration options
- [Troubleshooting](TROUBLESHOOTING.md) - Common issues and fixes
- [Architecture](ARCHITECTURE.md) - 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](https://github.com/docker/mcp-gateway/pull/263) - Tool name prefix separator (`:` → `__`)
- [PR #278](https://github.com/docker/mcp-gateway/pull/278) - Prefixed names sent to remote servers
- [PR #279](https://github.com/docker/mcp-gateway/pull/279) - Claude clients excluded from tool activation
**Recommendation**: Use standalone installation (Option A) until these PRs are merged.
---
## License
MIT
---
<div align="center">
**[Report Bug](https://github.com/null-runner/chrome-mcp-docker/issues)** · **[Request Feature](https://github.com/null-runner/chrome-mcp-docker/issues)**
Made with ☕ by [null-runner](https://github.com/null-runner)
</div>
