Puppeteer MCP fails to launch Chromium in Ubuntu (WSL) due to sandbox/X display issues

[lincbal4]

Describe the Bug:
I'm running Claude Code in a Ubuntu (WSL) terminal inside VS Code. Whenever Claude Code attempts to use the installed Puppeteer MCP, I receive the following error:

MCP error -32603: Failed to launch the browser process! undefined
[34032:34032:0312/155258.924001:ERROR:zygote_host_impl_linux.cc(101)] Running as root without --no-sandbox is not supported. See https://crbug.com/638180.
TROUBLESHOOTING: https://pptr.dev/troubleshooting

Steps to Reproduce:

1. Open VS Code and launch the Ubuntu (WSL) terminal.
2. Install the Puppeteer MCP with:
   claude mcp add puppeteer -- npx @modelcontextprotocol/server-puppeteer
3. Start Claude Code by running:
   claude
4. Notice that the MCP servers are listed as connected
5. Use Puppeteer (e.g., navigate to http://localhost:3001/).
6. The error regarding "Running as root without --no-sandbox" appears.

Expected Behavior:
I expect Puppeteer to launch Chromium successfully—ideally in headless mode or with the proper sandbox flags—so that the browser process starts without error.

Logs:
MCP error -32603: Failed to launch the browser process! undefined
[34032:34032:0312/155258.924001:ERROR:zygote_host_impl_linux.cc(101)] Running as root without --no-sandbox is not supported. See https://crbug.com/638180.
TROUBLESHOOTING: https://pptr.dev/troubleshooting

Additional Context:

• I'm using Ubuntu (WSL) within VS Code's terminal.
• The Puppeteer MCP was installed using:
  claude mcp add puppeteer -- npx @modelcontextprotocol/server-puppeteer
• I have tried removing and reinstalling the MCP server, and even attempted running as a non-root user (by creating a new user in WSL and re-adding the MCP).
• I also attempted to force headless mode by setting the environment variable with:
  claude mcp add puppeteer -e DOCKER_CONTAINER=true -- npx @modelcontextprotocol/server-puppeteer
  but either I still get the sandbox error or, if it switches to headful mode, I get an error about a missing X server ($DISPLAY).
• Both MCP servers (brave-search and puppeteer) are shown as connected, yet Puppeteer fails when used.

Any help resolving this issue would be greatly appreciated.

[Ar4v1nd]

Facing the same issue but only when using docker to host the puppeteer MCP (I'm using a Macbook with Apple M silicon). When inspecting the puppeteer MCP through inspector, I'm able to connect to the MCP server successfully and when trying to test one of the tools (puppeteer-navigate) from the inspector UI, I'm getting the exact same error as mentioned above.

I tried installing the puppeteer MCP through npx locally and was able to see the Chrome browser window getting opened on my macbook (since puppeteer installed through npx is documented to be not headless). But that brought in another issue when my MCP client was stuck waiting forever for the puppeteer tool call result (which never came back) and I had to eventually kill my client.

@lincbal4 Are you running Ubuntu on an arm64 based system? If so, this might help - puppeteer/puppeteer#7740 (got this from the MCP server-puppeteer dockerfile).

[lincbal4]

@Ar4v1nd ,

I ran into the same “Running as root without --no-sandbox” and “Missing X server or $DISPLAY” errors in my Ubuntu (WSL) environment when using the Puppeteer MCP in Claude Code. Here’s exactly how I fixed it:

1. Install Xvfb (a virtual X server):

   Since my environment didn’t have a display server, Puppeteer’s headful mode couldn’t launch. I installed Xvfb using the following commands (run as root):

   sudo apt-get update
   sudo apt-get install xvfb

2. Wrap the Puppeteer Command with xvfb-run:

   Next, I removed the existing Puppeteer MCP server and re-added it, wrapping the command with xvfb-run -a. This launches Puppeteer on a virtual display:

   claude mcp remove puppeteer

   claude mcp add puppeteer -- xvfb-run -a npx -y @modelcontextprotocol/server-puppeteer

3. Launch and Test in Claude Code:

   I then started Claude Code and checked that the MCP server was connected:

   claude

   At the Claude prompt, I ran:

   puppeteer_navigate url="https://example.com"

   puppeteer_screenshot name="example_screenshot"

   This successfully navigated to the site and took a screenshot—no more sandbox or X server errors!

In summary, by installing Xvfb and wrapping the Puppeteer command with xvfb-run -a, I was able to bypass the missing display issue and let Puppeteer launch Chromium properly. Depending on your setup, another option might be to run as a non-root user, but for my case, the Xvfb solution was the simplest fix.

Hope this helps!