How to Configure a Proxy Server in Chrome DevTools MCP

You can configure a proxy server in Chrome DevTools MCP by passing the --proxyServer or --proxy-server command-line flag, which the MCP server forwards directly to the Chromium instance as a startup argument.

The Chrome DevTools MCP repository (ChromeDevTools/chrome-devtools-mcp) provides a Model Context Protocol server that launches and controls Chrome browser instances. When your network environment requires traffic routing through a proxy, the MCP server exposes a dedicated CLI option that injects the standard Chromium --proxy-server argument during browser initialization.

Understanding the Proxy Configuration Architecture

The proxy configuration flows through two critical source files, transforming a user-supplied CLI flag into a Chromium startup argument.

CLI Flag Definition in src/cli.ts

The --proxyServer option is defined in src/cli.ts at lines 42-45, where the argument parser accepts a string value and maps it to the internal configuration object.

// src/cli.ts (lines 42-45)
.option('--proxyServer <url>', 'Proxy server URL (e.g., http://proxy.example.com:8080)')

The flag accepts both camelCase (--proxyServer) and kebab-case (--proxy-server) formats due to standard CLI parser normalization.

Browser Launch Integration in src/main.ts

When the MCP server launches Chrome, src/main.ts at lines 84-86 appends the proxy value to the Chromium argument list using the standard --proxy-server=<value> syntax.

// src/main.ts (lines 84-86)
if (config.proxyServer) {
  chromeArgs.push(`--proxy-server=${config.proxyServer}`);
}

Chromium reads this startup flag and routes all network traffic through the specified proxy without requiring additional code changes in the MCP server.

How to Use the Proxy Server Flag

You can configure the proxy through command-line invocation, external MCP proxy tools, or programmatic embedding.

Basic CLI Usage

Run the MCP server directly with the --proxyServer flag to route Chrome traffic through your proxy:

# HTTP proxy configuration

npx chrome-devtools-mcp --proxyServer=http://127.0.0.1:3128

# HTTPS proxy with authentication (if supported by Chromium)

npx chrome-devtools-mcp --proxyServer=https://user:pass@proxy.example.com:8080

The kebab-case variant works identically:

npx chrome-devtools-mcp --proxy-server=socks5://localhost:1080

Using with MCP Proxy Tools

When deploying behind an external MCP proxy such as mcp-proxy, pass the proxy flag through the command substitution:

mcp-proxy --transport streamablehttp --port 8080 -- \
  npx -y chrome-devtools-mcp@latest --proxyServer=http://proxy.company:3128

This configuration exposes the MCP server on port 8080 while ensuring all Chrome browser instances route traffic through the corporate proxy at proxy.company:3128.

Programmatic Configuration

If you embed the library directly in a TypeScript application, pass the proxyServer option to the runServer function:

import { runServer } from 'chrome-devtools-mcp';

await runServer({
  proxyServer: 'http://proxy.example:8000',
  // Additional MCP configuration options
  headless: false,
  port: 9222
});

The runServer wrapper forwards the proxyServer value to the same internal logic defined in src/main.ts, ensuring consistent behavior between CLI and programmatic usage.

Supported Proxy Protocols and Formats

Chromium's --proxy-server flag supports multiple proxy schemes that Chrome DevTools MCP inherits:

• HTTP proxies: http://proxy.example.com:8080
• HTTPS proxies: https://secure-proxy.example.com:8080
• SOCKS v5: socks5://localhost:1080
• SOCKS v4: socks4://proxy.example.com:1080
• Proxy bypass lists: Combine with --proxy-bypass-list (not directly exposed by MCP, but can be added via chromeArgs if extending the source)

The proxy configuration is optional; omitting the --proxyServer flag launches Chrome with default system network settings.

Summary

• Chrome DevTools MCP supports proxy configuration through the --proxyServer (or --proxy-server) CLI flag.
• The flag is defined in src/cli.ts (lines 42-45) and applied in src/main.ts (lines 84-86) as a Chromium startup argument.
• You can configure HTTP, HTTPS, SOCKS4, and SOCKS5 proxies using standard URL syntax.
• The proxy setting works identically across CLI invocation, MCP proxy tools, and programmatic runServer usage.

Frequently Asked Questions

Is the proxy configuration mandatory for Chrome DevTools MCP?

No, the proxy configuration is entirely optional. If you omit the --proxyServer flag, the MCP server launches Chrome with its default network configuration, using system proxy settings or direct connection depending on the operating system environment.

What proxy protocols does Chrome DevTools MCP support?

Chrome DevTools MCP inherits Chromium's proxy capabilities, supporting HTTP, HTTPS, SOCKS v4, and SOCKS v5 protocols. You specify the protocol using standard URL schemes (e.g., socks5://localhost:1080 or http://proxy.company:8080) in the --proxyServer argument.

How do I troubleshoot proxy connection issues?

First, verify that the proxy URL format matches Chromium's expected syntax by testing the same URL with a standalone Chrome instance using --proxy-server=<url>. Check that the proxy is accessible from the MCP server's network environment. If authentication is required, ensure credentials are URL-encoded in the proxy string (e.g., http://user:pass@proxy:8080), though note that Chromium's support for proxy authentication varies by platform.

Can I configure proxy authentication in Chrome DevTools MCP?

Yes, you can include credentials directly in the proxy URL using standard HTTP authentication syntax: --proxyServer=http://username:password@proxy.example.com:8080. However, authentication support depends on Chromium's underlying implementation and the specific proxy protocol. For enterprise environments requiring complex authentication schemes, consider configuring system-wide proxy settings instead of using the MCP flag, as Chromium may handle system proxy configuration more robustly than command-line credentials.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}