Introduction

Ever wish your AI coding assistant could actually see what your code does in a browser? Instead of taking screenshots and describing errors manually, imagine telling your AI: “Go to that page, click the login button, and tell me what console errors appear.”

That’s exactly what Chrome DevTools MCP enables. Combined with OpenCode, you get an AI assistant that can browse websites, take screenshots, inspect network requests, and debug live web applications—all from your terminal.

This guide walks you through setting up Chrome DevTools MCP with OpenCode on Ubuntu from scratch. No prior MCP experience needed.

What Is Chrome DevTools MCP?

The Problem It Solves

Traditional AI coding assistants are “blind.” They can write code, but they can’t see:

  • What your page looks like after changes
  • Console errors happening in real-time
  • Network requests failing
  • Performance bottlenecks

You end up in a tedious loop: describe the problem → AI guesses a fix → you test it → report back → repeat.

Chrome DevTools MCP gives your AI “eyes” by connecting it directly to Chrome’s developer tools.

How It Works

Chrome DevTools MCP is an official Google tool that bridges AI assistants to Chrome via the Model Context Protocol (MCP)—an open standard that lets AI tools communicate with external applications.

You → OpenCode → Chrome DevTools MCP → Chrome Browser

Once set up, your AI can:

  • Navigate to any URL
  • Click buttons and fill forms
  • Read console logs and network requests
  • Take screenshots
  • Run performance audits

Prerequisites

Before starting, make sure you have:

  1. Ubuntu 22.04 or newer
  2. Node.js v20.19+ (check with node --version)
  3. Google Chrome installed (check with google-chrome --version)
  4. OpenCode installed

Quick Check

Open your terminal and run:

node --version
google-chrome --version

If Node.js is missing, install it:

# For Ubuntu 24.04+
sudo apt update
sudo apt install nodejs npm

# Or use NodeSource for newer versions
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

Step 1: Launch Chrome with Remote Debugging

This is the most important step.

Chrome needs a special flag to let AI tools connect to it:

google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

What these flags do:

  • --remote-debugging-port=9222 — Opens port 9222 for DevTools connections
  • --user-data-dir=/tmp/chrome-debug — Uses a separate profile (required! Chrome won’t allow debugging with your default profile)

Important: Chrome requires --user-data-dir to be different from your default profile. This is a security feature. If you see “DevTools remote debugging requires a non-default data directory”, you forgot this flag.

Quick Alias

Add this to your ~/.bashrc for easy access:

echo 'alias chromedebug="google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug"' >> ~/.bashrc
source ~/.bashrc

Now you can just type chromedebug to launch Chrome with debugging enabled.

Step 2: Configure OpenCode

Find Your OpenCode Config Location

OpenCode stores its global configuration at:

~/.config/opencode/opencode.json

Create the directory if it doesn’t exist:

mkdir -p ~/.config/opencode

Create the Configuration File

nano ~/.config/opencode/opencode.json

Add This Configuration

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "chrome-devtools": {
      "type": "local",
      "command": ["npx", "-y", "chrome-devtools-mcp@latest", "--browserUrl", "http://127.0.0.1:9222"],
      "enabled": true
    }
  }
}

What each part means:

  • chrome-devtools — A unique name for this MCP server
  • type: "local" — Tells OpenCode this runs locally on your machine
  • command — The command array to launch the MCP server
  • --browserUrl http://127.0.0.1:9222 — Tells MCP to connect to your running Chrome
  • enabled: true — Activates this MCP server on startup

Save the file (Ctrl+O, Enter, Ctrl+X in nano).

Step 3: Restart OpenCode

After saving the config, close and restart OpenCode completely.

This is crucial—OpenCode only reads the config file when it starts.

Step 4: Verify It Works

Check Chrome is Running

First, make sure Chrome is running with debugging:

curl http://127.0.0.1:9222/json/version

You should see something like:

{
  "Browser": "Chrome/148.0.0.0",
  "Protocol-Version": "1.3",
  "webSocketDebuggerUrl": "ws://127.0.0.1:9222/devtools/browser/..."
}

If this fails, Chrome isn’t running with --remote-debugging-port=9222.

Test in OpenCode

Start a new OpenCode session and try:

List the open pages in Chrome.

You should see your Chrome tabs listed.

Try a Real Task

Navigate to https://example.com and take a screenshot.

If the AI responds with page content or a screenshot, everything is working!

Troubleshooting

“Not connected” Error

Problem: OpenCode DevTools tools show “Not connected”

Causes and fixes:

  1. Chrome not running with debugging

    # Check if Chrome is running with debugging
curl http://127.0.0.1:9222/json/version

    If this fails, Chrome isn’t running with --remote-debugging-port=9222.

  2. Wrong configuration Make sure your config has --browserUrl http://127.0.0.1:9222, not just --autoConnect.

  3. Chrome needs --user-data-dir Chrome refuses debugging without a separate user data directory.

  4. Restart OpenCode Config changes only take effect after restarting OpenCode.

Chrome Won’t Start with Debugging Port

Error: “DevTools remote debugging requires a non-default data directory”

Fix: Always include --user-data-dir:

google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

MCP Config Syntax Mistakes

Common errors in JSON:

  • Missing commas between items
  • Using single quotes instead of double quotes
  • Trailing commas after the last item

Always validate your JSON at jsonlint.com if things aren’t working.

Port Already in Use

If port 9222 is taken:

# Find what's using it
lsof -i :9222

# Kill it if needed
kill <PID>

Making Chrome Start Automatically (Optional)

Want Chrome to start with debugging automatically when you log in?

Method 1: Desktop Launcher

Create a .desktop file:

nano ~/.local/share/applications/chrome-debug.desktop

Add:

[Desktop Entry]
Name=Chrome (Debug)
Exec=google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug
Icon=google-chrome
Terminal=false
Type=Application

Method 2: Systemd Service (Advanced)

For a service that auto-starts:

sudo nano /etc/systemd/system/chrome-debug.service

[Unit]
Description=Chrome with Remote Debugging

[Service]
ExecStart=/usr/bin/google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug
User=YOUR_USERNAME
Restart=on-failure

[Install]
WantedBy=default.target

Enable it:

sudo systemctl daemon-reload
sudo systemctl enable chrome-debug
sudo systemctl start chrome-debug

Security Notes

Keep It Safe

  1. Don’t use --no-sandbox in production — it disables Chrome’s security
  2. Use a dedicated profile (/tmp/chrome-debug) instead of your main profile
  3. Close Chrome when done debugging sensitive applications
  4. Review AI actions — the AI can navigate anywhere and read page content

Understanding the Risks

Chrome DevTools MCP gives your AI significant browser access:

  • Read all page content and cookies
  • Execute JavaScript
  • Navigate to any URL
  • Perform actions (clicks, form submissions)

Only use it with trusted AI models and code.

Quick Reference

Commands Summary

Action Command
Launch Chrome with debugging google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug
Check if Chrome is responding curl http://127.0.0.1:9222/json/version
Restart OpenCode Exit and run opencode again

Minimal Working Config

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "chrome-devtools": {
      "type": "local",
      "command": ["npx", "-y", "chrome-devtools-mcp@latest", "--browserUrl", "http://127.0.0.1:9222"],
      "enabled": true
    }
  }
}

Summary

The setup process is simple:

  1. Launch Chrome with --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug
  2. Configure OpenCode in ~/.config/opencode/opencode.json
  3. Use --browserUrl http://127.0.0.1:9222 to connect to your Chrome
  4. Restart OpenCode to load the config
  5. Test by asking the AI to list pages or take a screenshot

Once working, your AI assistant can browse, inspect, and debug live web applications alongside you.

SEO Keywords

  • Chrome DevTools MCP
  • OpenCode MCP setup
  • Ubuntu Chrome DevTools AI
  • Model Context Protocol tutorial
  • AI browser debugging
  • Chrome DevTools OpenCode Ubuntu

Suggested Social Media Post

Just set up Chrome DevTools MCP with OpenCode! Now my AI can see what my code does in a real browser—no more blind coding. Screenshots, network analysis, console logs—15-minute setup. 🚀