What Is This About?

This guide shows you how to connect OpenCode (an AI coding assistant) to Chrome so your AI can actually see and interact with web pages.

Imagine being able to say:

  • “Go to my app, click the login button, and tell me what happens”
  • “Take a screenshot of the homepage”
  • “Check for console errors on the checkout page”

Without doing any of it manually yourself. That’s what this setup enables.

What You’ll Need

  • Ubuntu 22.04 or newer
  • Node.js v20.19+ (node --version)
  • Google Chrome installed (google-chrome --version)
  • OpenCode installed

Quick Check

Run these in your terminal:

node --version
google-chrome --version

If Node.js is missing:

sudo apt update
sudo apt install nodejs npm

Step 1: Launch Chrome with Debugging Enabled

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 mean:

  • --remote-debugging-port=9222 — Opens a door for AI tools to connect
  • --user-data-dir=/tmp/chrome-debug — Uses a separate profile (required!)

Why --user-data-dir? Chrome won’t allow debugging with your regular profile. It must be a separate directory.

Verify Chrome is Ready

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

You should see JSON output like:

{
  "Browser": "Chrome/148.0.0.0",
  "Protocol-Version": "1.3"
}

If you see an error, Chrome isn’t running with the debugging flag.

Step 2: Configure OpenCode

Find Your Config File

OpenCode stores settings at:

~/.config/opencode/opencode.json

Create the directory first:

mkdir -p ~/.config/opencode

Create the Config File

nano ~/.config/opencode/opencode.json

Add This Exact 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
    }
  }
}

Important: Use --browserUrl http://127.0.0.1:9222 to connect to your running Chrome. The alternative --autoConnect flag requires Chrome 144+ with remote debugging enabled via chrome://inspect/#remote-debugging.

Save with Ctrl+O, then Enter, then Ctrl+X to exit.

Step 3: Restart OpenCode

Close OpenCode completely and reopen it.

The config file is only read when OpenCode starts. Changes won’t work if OpenCode is already running.

Step 4: Test It Out

Test 1: List Open Tabs

Start a new OpenCode session and type:

List the open pages in Chrome.

You should see your Chrome tabs listed.

Test 2: Navigate and Screenshot

Try:

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

Test 3: Real Browsing

Search YouTube for "lofi music" and click on the first video to play it.

If the AI responds with page content or confirms actions, it’s working!

Common Problems and Solutions

“Not connected” Error

What it looks like: OpenCode DevTools tools show “Not connected”

Check these things:

  1. Is Chrome running with debugging?

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

    If this fails, Chrome isn’t set up right. Go back to Step 1.

  2. Did you restart OpenCode? The config only loads on startup.

  3. Is your config file correct? The --browserUrl flag must be included.

Chrome Won’t Start with Debugging Port

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

Fix: You forgot the --user-data-dir flag:

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

Config File JSON Errors

JSON is picky. Common mistakes:

  • Using ' instead of "
  • Missing commas between items
  • Extra commas after the last item

Use jsonlint.com to validate your config.

Making It Easier: Desktop Launcher

Instead of typing the command every time, create a .desktop file to launch Chrome from your app menu:

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

Add:

[Desktop Entry]
Name=Chrome MCP
Comment=Chrome with Remote Debugging for MCP
Exec=google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug
Icon=google-chrome
Terminal=false
Type=Application
Categories=Network;WebBrowser;
StartupNotify=false

Then make it executable:

chmod +x ~/.local/share/applications/chrome-mcp.desktop

Now search for “Chrome MCP” in your app menu to launch it with debugging enabled.

Making It Easier: Create an Alias

Add this line to your ~/.bashrc so you can type just chromedebug:

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

Now launching Chrome for debugging is as simple as:

chromedebug

Understanding the Security Aspect

This setup gives your AI access to:

  • Read all web page content
  • See your cookies and login sessions
  • Click buttons and fill forms
  • Navigate to any website

Stay safe:

  1. Use the /tmp/chrome-debug profile (not your main one)
  2. Don’t run --no-sandbox (it’s a security risk)
  3. Close Chrome when done with sensitive browsing
  4. Be careful what you ask the AI to do

Quick Reference Card

You want to… Do this…
Launch Chrome for debugging google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug
Check if it’s working curl http://127.0.0.1:9222/json/version
Open config file nano ~/.config/opencode/opencode.json
Test in OpenCode List the open pages in Chrome.

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

Setup takes about 5 minutes:

  1. Launch Chrome with the debugging flags
  2. Create config at ~/.config/opencode/opencode.json
  3. Add the MCP server config with --browserUrl http://127.0.0.1:9222
  4. Restart OpenCode
  5. Test by asking the AI to browse or screenshot something

Once working, your AI assistant becomes a powerful browser-aware debugging partner.

SEO Keywords

Chrome DevTools MCP, OpenCode Chrome setup, Ubuntu MCP tutorial, AI browser debugging, Chrome DevTools for AI, MCP server configuration, AI coding assistant browser

Suggested Social Media Post

Gave my AI coding assistant “eyes” today!

Chrome DevTools MCP + OpenCode = browse websites, take screenshots, check console errors—all from the terminal.

5-minute setup. No API keys needed.