# How to Configure a Proxy Server in Chrome DevTools MCP

> Learn to configure a proxy server in Chrome DevTools MCP easily. This guide shows how to effectively use the --proxyServer flag for seamless integration with Chromium.

- Repository: [ChromeDevTools/chrome-devtools-mcp](https://github.com/chromedevtools/chrome-devtools-mcp)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/cli.ts) at lines 42-45, where the argument parser accepts a string value and maps it to the internal configuration object.

```typescript
// 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`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/main.ts) at lines 84-86 appends the proxy value to the Chromium argument list using the standard `--proxy-server=<value>` syntax.

```typescript
// 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:

```bash

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

```bash
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:

```bash
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:

```typescript
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`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/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`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/cli.ts)** (lines 42-45) and applied in **[`src/main.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/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.