Content
# Chrome DevTools MCP for Hermes Agent — Complete Guide
> **Status:** Active
> **Version:** MCP Server v35+ tools
---
## What is This
Chrome DevTools MCP (Model Context Protocol) — direct access to Chrome DevTools Protocol.
**35+ tools** vs ~12 in `chrome-cdp` skill.
Capabilities:
- Read and control any page in Chrome
- Screenshots, snapshots, JS execution
- Intercept network, console, errors
- Performance tracing, Lighthouse audit
- Device emulation, geolocation, user agent
---
## Requirements
### 1. Chrome with Remote Debugging
Supported:
- **Chrome Stable** (with `--remote-debugging-port=9222`)
- **Chrome Beta** — recommended
- **Chrome Canary** — recommended
Check which Chrome is running:
```bash
ps aux | grep -i "Google Chrome" | grep -v grep | head -5
```
### 2. Hermes Agent
Minimum version with MCP support. Check:
```bash
hermes version 2>/dev/null || echo "Update hermes"
```
---
## Installation
### Step 1 — Add to config.yaml
```yaml
mcp_servers:
chrome-devtools:
command: npx
args:
- -y
- chrome-devtools-mcp@latest
- --autoConnect
- --channel=stable
```
**Channel options:**
- `stable` — stable Chrome
- `beta` — beta (if stable fails)
- `canary` — Canary
### Step 2 — Restart Gateway
```bash
hermes gateway restart
```
### Step 3 — Verify
```bash
hermes tools 2>/dev/null | grep mcp_chrome_devtools
```
All tools should appear.
### Step 4 — Connect Chrome (if needed)
If Chrome doesn't auto-connect, launch Chrome with flag:
```bash
# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
--remote-debugging-port=9222
# or Beta:
/Applications/Google\ Chrome\ Beta.app/Contents/MacOS/Google\ Chrome\ Beta \
--remote-debugging-port=9222
# or Canary:
/Applications/Google\ Chrome\ Canary.app/Contents/MacOS/Google\ Chrome\ Canary \
--remote-debugging-port=9222
```
> **Note:** Chrome will ask for permission on first CDP connection. Allow it.
---
## Alternative: Enable via chrome://inspect
If Chrome is already running, you can enable remote debugging without restart:
1. Open `chrome://inspect/#remote-debugging` in a tab
2. Check the box: **"Allow remote debugging for this browser instance"**
3. Chrome will now accept CDP connections on port 9222
This is the easiest way when Chrome is already open with many tabs.
---
## Tools — Full List
### Navigation
| Tool | Description |
|------|-------------|
| `list_pages` | List all open tabs |
| `select_page` | Switch to a tab |
| `new_page` | Open new tab |
| `close_page` | Close tab |
| `navigate_page` | Navigate to URL |
| `wait_for` | Wait for text on page |
### Automation
| Tool | Description |
|------|-------------|
| `click` | Click element (by uid) |
| `hover` | Hover over element |
| `drag` | Drag element to another |
| `fill` | Type text into field |
| `fill_form` | Fill multiple fields |
| `type_text` | Type text (after focus) |
| `press_key` | Press key (Enter, Tab, Escape, etc.) |
| `upload_file` | Upload file |
| `handle_dialog` | Accept/dismiss dialog |
### Screenshots & Snapshots
| Tool | Description |
|------|-------------|
| `take_snapshot` | Text snapshot (a11y tree) |
| `take_screenshot` | Page screenshot (PNG) |
| `take_snapshot verbose=true` | Full a11y tree |
### JavaScript
| Tool | Description |
|------|-------------|
| `evaluate_script` | Execute arbitrary JS |
| `list_console_messages` | Console logs |
| `get_console_message` | Specific message by ID |
### Network
| Tool | Description |
|------|-------------|
| `list_network_requests` | All requests |
| `get_network_request` | Specific request |
### Performance
| Tool | Description |
|------|-------------|
| `performance_start_trace` | Start trace |
| `performance_stop_trace` | Stop and save |
| `performance_analyze_insight` | Insight details |
### Memory
| Tool | Description |
|------|-------------|
| `take_memory_snapshot` | JS heap snapshot |
### Emulation
| Tool | Description |
|------|-------------|
| `emulate viewport=1280x720` | Window size |
| `emulate colorScheme=dark` | Color scheme |
| `emulate geolocation=55x37` | Geolocation |
| `emulate userAgent="..."` | User Agent |
| `resize_page` | Resize page |
### Lighthouse
| Tool | Description |
|------|-------------|
| `lighthouse_audit` | Audit accessibility, SEO, best practices |
---
## Usage Examples
### List Open Tabs
```
mcp_chrome_devtools_list_pages
```
Response:
```
1: https://www.threads.com/ [selected]
2: https://github.com/glincker/thesvg
3: https://web.telegram.org/a/#8********
```
### Take Page Snapshot
```
mcp_chrome_devtools_take_snapshot()
```
### Click Button
1. Take snapshot — find element uid
2. `mcp_chrome_devtools_click(uid="e42")`
### Fill Form
```
mcp_chrome_devtools_fill_form(elements=[
{"uid": "e12", "value": "email@example.com"},
{"uid": "e14", "value": "your_password"}
])
```
### Execute JS
```
mcp_chrome_devtools_evaluate_script(
function="() => document.title"
)
```
### Screenshot Page
```
mcp_chrome_devtools_take_screenshot(
format="png",
fullPage=true
)
```
---
## Config (~/.hermes/config.yaml)
### 1. MCP Server
```yaml
mcp_servers:
chrome-devtools:
command: npx
args:
- -y
- chrome-devtools-mcp@latest
- --autoConnect
- --channel=stable
```
### 2. Browser Section (CDP URL)
> **Important:** This is **NOT** in `mcp_servers`. Separate `browser:` section.
```yaml
browser:
cdp_url: ws://127.0.0.1:9222 # WebSocket URL for Chrome DevTools Protocol
inactivity_timeout: 120
command_timeout: 30
record_sessions: true
```
`cdp_url` points to Chrome with remote debugging. Chrome must be launched with `--remote-debugging-port=9222`.
---
## How It Works
```
┌─────────────────┐ WebSocket ┌──────────────────┐ CDP ┌────────────┐
│ chrome-devtools │ ──────────────► │ Chrome with │ ◄───────── │ Live │
│ MCP (npx) │ │ --remote- │ │ Chrome │
│ │ ◄────────────── │ debugging=9222 │ │ (tabs) │
└─────────────────┘ └──────────────────┘ └────────────┘
```
1. Chrome runs with `--remote-debugging-port=9222` — opens WebSocket
2. `chrome-devtools-mcp` connects to `ws://127.0.0.1:9222`
3. Hermes uses `cdp_url` for browser tools
---
## Troubleshooting
### "Connection refused" / Empty Response
1. Verify Chrome is running with remote debugging:
```bash
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
--remote-debugging-port=9222
```
2. Check `cdp_url` is correct:
```bash
grep cdp_url ~/.hermes/config.yaml
```
Should be: `ws://127.0.0.1:9222`
3. Try different channel (beta/canary):
```yaml
args:
- -y
- chrome-devtools-mcp@latest
- --autoConnect
- --channel=beta
```
### Chrome Prompts for Permission
This is normal on first connection. Allow in Chrome window.
### Tools Don't Appear After Restart
```bash
hermes gateway restart
# Wait 5 seconds
hermes tools 2>/dev/null | grep chrome
```
### "Target closed" When Working with Tab
Page closed or reloaded. Get fresh tab list:
```
mcp_chrome_devtools_list_pages
```
---
## Files
| What | Path |
|------|------|
| Config | `~/.hermes/config.yaml` |
| Repository | https://github.com/Maatq1544/hermes-chrome-devtools-mcp |
---
## License
MIT — see [LICENSE](LICENSE)
## Author
Agent Hermes — Lisa Carter
[GitHub @Maatq1544](https://github.com/Maatq1544)
