If you are using Claude Code and want it to interact with a real browser - navigating pages, taking screenshots, clicking elements - the Chrome DevTools MCP server is the way to go.

On Linux with Wayland, getting this to work requires a few extra steps. Here is what I learned.

The problem

The Chrome DevTools MCP server uses Puppeteer under the hood. When you add it to your Claude Code config in ~/.claude.json like this:

{
  "mcpServers": {
    "chrome-devtools-npx": {
      "type": "stdio",
      "command": "npx",
      "args": ["chrome-devtools-mcp@latest"],
      "env": {}
    }
  }
}

...and try to use it, you will get an error like:

Missing X server to start the headful browser.
Either set headless to true or use xvfb-run to run your Puppeteer script.

This happens because Puppeteer tries to launch Chrome with X11, but your system is running Wayland.

First attempt: connecting to a running Chrome instance

One approach is to start Chrome yourself with remote debugging enabled and then point the MCP server at it:

google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug-profile --ozone-platform=wayland

Then configure the MCP server to connect to it:

{
  "chrome-devtools-npx": {
    "type": "stdio",
    "command": "npx",
    "args": ["chrome-devtools-mcp@latest"],
    "env": {
      "CHROME_CDP_URL": "http://localhost:9222"
    }
  }
}

This works, but you have to manually start Chrome with the right flags every time before using the MCP tools. Not great.

The solution: let the MCP server launch Chrome with the right flags

The chrome-devtools-mcp CLI supports --chromeArg flags that get passed through to Chrome when the MCP server launches it. This means we can tell it to use Wayland - and suppress the annoying first-run dialogs at the same time.

Here is the final config in ~/.claude.json:

{
  "mcpServers": {
    "chrome-devtools-npx": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "chrome-devtools-mcp@latest",
        "--chromeArg=--ozone-platform=wayland",
        "--chromeArg=--no-first-run",
        "--chromeArg=--no-default-browser-check",
        "--chromeArg=--disable-search-engine-choice-screen",
        "--no-usage-statistics",
        "--isolated"
      ],
      "env": {}
    }
  }
}

Let me break down the flags:

• --chromeArg=--ozone-platform=wayland - tells Chrome to use the Wayland backend instead of X11
• --chromeArg=--no-first-run - skips the "Welcome to Chrome" dialog
• --chromeArg=--no-default-browser-check - skips the "Set as default browser?" prompt
• --chromeArg=--disable-search-engine-choice-screen - skips the search engine selection screen
• --no-usage-statistics - disables Google's usage statistics collection in the MCP server
• --isolated - uses a temporary profile directory that gets cleaned up when Chrome closes

The --isolated flag is important: without it, the MCP server stores its Chrome profile in ~/.cache/chrome-devtools-mcp/chrome-profile/. If a previous Chrome instance is still running (or was not shut down cleanly), launching a new one will fail with "The browser is already running" because two Chrome instances cannot share the same profile directory. With --isolated, each session gets its own temporary profile, avoiding this conflict entirely.

With this configuration, Claude Code will automatically launch a Chrome window when it needs browser access. No manual Chrome start required.

Using it

After restarting Claude Code, you can use the Chrome DevTools tools right away. Claude can navigate to URLs, take screenshots, click elements, fill forms, inspect network requests, and more - all through the MCP tools.

Available CLI flags

The chrome-devtools-mcp CLI has quite a few options worth knowing about:

npx chrome-devtools-mcp@latest --help

Some useful ones:

• --headless - run Chrome without a visible window
• --viewport 1280x720 - set the initial viewport size
• --slim - only expose 3 tools (navigation, JavaScript execution, screenshot) instead of the full set
• --browserUrl http://127.0.0.1:9222 - connect to an already running Chrome instance
• --isolated - use a temporary profile that gets cleaned up when Chrome closes
• --channel canary - use Chrome Canary instead of stable

Wrapping up

The key insight is that the Chrome DevTools MCP server can launch Chrome on its own - you just need to pass the right platform flags via --chromeArg. On Wayland, that means --ozone-platform=wayland. Once configured, it just works.