brave-mcp 0.1.0

package/README.md

@@ -0,0 +1,802 @@
+# Brave MCP
+
+> Fork of [ChromeDevTools/chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp) ported to **Brave Browser**.
+>
+> npm: `brave-mcp` · repo: `triuzzi/brave-devtools-mcp`
+
+`brave-mcp` lets your coding agent (such as Claude, Cursor, Gemini or Copilot)
+control and inspect a live Brave browser. It acts as a Model-Context-Protocol
+(MCP) server, giving your AI coding assistant access to the full power of
+DevTools for reliable automation, in-depth debugging, and performance analysis.
+
+## [Tool reference](./docs/tool-reference.md) | [Changelog](./CHANGELOG.md) | [Contributing](./CONTRIBUTING.md) | [Troubleshooting](./docs/troubleshooting.md) | [Design Principles](./docs/design-principles.md)
+
+## Key features
+
+- **Get performance insights**: Uses [Chrome
+  DevTools](https://github.com/ChromeDevTools/devtools-frontend) to record
+  traces and extract actionable performance insights.
+- **Advanced browser debugging**: Analyze network requests, take screenshots and
+  check browser console messages (with source-mapped stack traces).
+- **Reliable automation**. Uses
+  [puppeteer](https://github.com/puppeteer/puppeteer) to automate actions in
+  Brave and automatically wait for action results.
+
+## Disclaimers
+
+`brave-devtools-mcp` exposes content of the browser instance to the MCP clients
+allowing them to inspect, debug, and modify any data in the browser or DevTools.
+Avoid sharing sensitive or personal information that you don't want to share with
+MCP clients.
+
+Performance tools may send trace URLs to the Google CrUX API to fetch real-user
+experience data. To disable this, run with the `--no-performance-crux` flag.
+
+Usage statistics from the upstream project are **disabled by default** in this fork.
+You can explicitly enable them with `--usage-statistics` if desired.
+
+## Requirements
+
+- [Node.js](https://nodejs.org/) v20.19 or a newer [latest maintenance LTS](https://github.com/nodejs/Release#release-schedule) version.
+- [Brave Browser](https://brave.com/) current release version or newer.
+- [npm](https://www.npmjs.com/)
+
+> **Note:** Do **not** use `chrome-devtools-mcp@latest` from npm — that installs Google's Chrome-oriented server. This fork is `brave-mcp`.
+
+## Setup
+
+### Quick start (via npm)
+
+```json
+{
+  "mcpServers": {
+    "brave-devtools": {
+      "command": "npx",
+      "args": ["-y", "brave-mcp@latest"]
+    }
+  }
+}
+```
+
+Add this to your MCP client config and you're done. Works with **Claude Code** (`~/.mcp.json`), **Cursor** (Settings → MCP), **VS Code Copilot**, and any other MCP client.
+
+### From source (for development)
+
+```sh
+git clone https://github.com/triuzzi/brave-devtools-mcp.git
+cd brave-devtools-mcp
+npm install
+npm run build
+```
+
+Run `npm run build` again after `git pull` when you update the repo.
+
+Then point your MCP config at the built CLI with an **absolute path**:
+
+```json
+{
+  "mcpServers": {
+    "brave-devtools": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/brave-devtools-mcp/build/src/bin/brave-devtools-mcp.js"
+      ]
+    }
+  }
+}
+```
+
+This works with **Claude Code** (`~/.mcp.json`), **Cursor** (Settings → MCP → New MCP Server, or `mcp.json`), **VS Code Copilot**, and any other MCP client.
+
+If Brave is not detected automatically, set `BRAVE_PATH`:
+
+```json
+{
+  "mcpServers": {
+    "brave-devtools": {
+      "command": "node",
+      "args": ["/absolute/path/to/brave-devtools-mcp/build/src/bin/brave-devtools-mcp.js"],
+      "env": {
+        "BRAVE_PATH": "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
+      }
+    }
+  }
+}
+```
+
+### 3. Choose your connection mode
+
+The server has two modes: **launch a new instance** (default) or **attach to your existing Brave window**.
+
+#### Mode A: Launch a new instance (default)
+
+With the basic config above, the server spawns a dedicated Brave instance with its own profile. Your existing Brave windows are untouched. This is the simplest mode — no extra setup needed.
+
+#### Mode B: Attach to your existing Brave window
+
+If you want the MCP server to control the Brave window you already have open (same tabs, cookies, logins), you need to start Brave with remote debugging enabled.
+
+**Step 1:** Quit Brave completely, then relaunch with the debugging flag:
+
+```sh
+# macOS
+open -a "Brave Browser" --args --remote-debugging-port=9222
+
+# Linux
+brave-browser --remote-debugging-port=9222
+
+# Windows
+"C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe" --remote-debugging-port=9222
+```
+
+> **Tip:** To always start Brave with remote debugging, add `--remote-debugging-port=9222` to Brave's launch shortcut or shell alias so you never have to think about it again.
+
+**Step 2:** Add `--browserUrl` to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "brave-devtools": {
+      "command": "npx",
+      "args": ["-y", "brave-mcp@latest", "--browserUrl", "http://localhost:9222"]
+    }
+  }
+}
+```
+
+Or if running from source:
+
+```json
+{
+  "mcpServers": {
+    "brave-devtools": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/brave-devtools-mcp/build/src/bin/brave-devtools-mcp.js",
+        "--browserUrl", "http://localhost:9222"
+      ]
+    }
+  }
+}
+```
+
+Without `--browserUrl`, the server will always launch a new instance. With it, the server attaches to your running Brave instead.
+
+> **Warning:** The remote debugging port lets any application on your machine control the browser. Be mindful of sensitive websites while it's open.
+
+### All CLI options
+
+Run `--help` to see every flag:
+
+```sh
+node /absolute/path/to/brave-devtools-mcp/build/src/bin/brave-devtools-mcp.js --help
+```
+
+## Testing
+
+An integration test suite exercises all 29 MCP tools against a running Brave instance:
+
+```sh
+# Launch Brave with remote debugging
+open -a "Brave Browser" --args --remote-debugging-port=9222
+
+# Run all 36 test cases
+npm run test:brave
+```
+
+Tests cover navigation, snapshots, screenshots, script execution, input automation (click/fill/drag/upload), dialogs, console, network, emulation, performance tracing, memory snapshots, and Lighthouse audits.
+
+## Getting started
+
+If you are interested in only basic browser tasks, use `--slim` mode:
+
+```json
+{
+  "mcpServers": {
+    "brave-devtools": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/brave-devtools-mcp/build/src/bin/brave-devtools-mcp.js",
+        "--slim", "--headless"
+      ]
+    }
+  }
+}
+```
+
+See [Slim tool reference](./docs/slim-tool-reference.md).
+
+### MCP Client configuration
+
+<details>
+  <summary>Amp</summary>
+  Follow https://ampcode.com/manual#mcp and use the config provided above. You can also install the Chrome DevTools MCP server using the CLI:
+
+```bash
+amp mcp add chrome-devtools -- npx chrome-devtools-mcp@latest
+```
+
+</details>
+
+<details>
+  <summary>Antigravity</summary>
+
+To use the Chrome DevTools MCP server follow the instructions from <a href="https://antigravity.google/docs/mcp">Antigravity's docs</a> to install a custom MCP server. Add the following config to the MCP servers config:
+
+```bash
+{
+  "mcpServers": {
+    "chrome-devtools": {
+      "command": "npx",
+      "args": [
+        "chrome-devtools-mcp@latest",
+        "--browser-url=http://127.0.0.1:9222",
+        "-y"
+      ]
+    }
+  }
+}
+```
+
+This will make the Chrome DevTools MCP server automatically connect to the browser that Antigravity is using. If you are not using port 9222, make sure to adjust accordingly.
+
+Chrome DevTools MCP will not start the browser instance automatically using this approach because the Chrome DevTools MCP server connects to Antigravity's built-in browser. If the browser is not already running, you have to start it first by clicking the Chrome icon at the top right corner.
+
+</details>
+
+<details>
+  <summary>Claude Code</summary>
+
+**Install via CLI (MCP only)**
+
+Use the Claude Code CLI to add the Chrome DevTools MCP server (<a href="https://code.claude.com/docs/en/mcp">guide</a>):
+
+```bash
+claude mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest
+```
+
+**Install as a Plugin (MCP + Skills)**
+
+> [!NOTE]
+> If you already had Chrome DevTools MCP installed previously for Claude Code, make sure to remove it first from your installation and configuration files.
+
+To install Chrome DevTools MCP with skills, add the marketplace registry in Claude Code:
+
+```sh
+/plugin marketplace add ChromeDevTools/chrome-devtools-mcp
+```
+
+Then, install the plugin:
+
+```sh
+/plugin install chrome-devtools-mcp
+```
+
+Restart Claude Code to have the MCP server and skills load (check with `/skills`).
+
+> [!TIP]
+> If the plugin installation fails with a `Failed to clone repository` error (e.g., HTTPS connectivity issues behind a corporate firewall), see the [troubleshooting guide](./docs/troubleshooting.md#claude-code-plugin-installation-fails-with-failed-to-clone-repository) for workarounds, or use the CLI installation method above instead.
+
+</details>
+
+<details>
+  <summary>Cline</summary>
+  Follow https://docs.cline.bot/mcp/configuring-mcp-servers and use the config provided above.
+</details>
+
+<details>
+  <summary>Codex</summary>
+  Follow the <a href="https://developers.openai.com/codex/mcp/#configure-with-the-cli">configure MCP guide</a>
+  using the standard config from above. You can also install the Chrome DevTools MCP server using the Codex CLI:
+
+```bash
+codex mcp add chrome-devtools -- npx chrome-devtools-mcp@latest
+```
+
+**On Windows 11**
+
+Configure the Chrome install location and increase the startup timeout by updating `.codex/config.toml` and adding the following `env` and `startup_timeout_ms` parameters:
+
+```
+[mcp_servers.chrome-devtools]
+command = "cmd"
+args = [
+    "/c",
+    "npx",
+    "-y",
+    "chrome-devtools-mcp@latest",
+]
+env = { SystemRoot="C:\\Windows", PROGRAMFILES="C:\\Program Files" }
+startup_timeout_ms = 20_000
+```
+
+</details>
+
+<details>
+  <summary>Command Code</summary>
+
+Use the Command Code CLI to add the Chrome DevTools MCP server (<a href="https://commandcode.ai/docs/mcp">MCP guide</a>):
+
+```bash
+cmd mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest
+```
+
+</details>
+
+<details>
+  <summary>Copilot CLI</summary>
+
+Start Copilot CLI:
+
+```
+copilot
+```
+
+Start the dialog to add a new MCP server by running:
+
+```
+/mcp add
+```
+
+Configure the following fields and press `CTRL+S` to save the configuration:
+
+- **Server name:** `chrome-devtools`
+- **Server Type:** `[1] Local`
+- **Command:** `npx -y chrome-devtools-mcp@latest`
+
+</details>
+
+<details>
+  <summary>Copilot / VS Code</summary>
+
+**Install as a Plugin (Recommended)**
+
+The easiest way to get up and running is to install `chrome-devtools-mcp` as an agent plugin.
+This bundles the **MCP server** and all **skills** together, so your agent gets both the tools
+and the expert guidance it needs to use them effectively.
+
+1.  Open the **Command Palette** (`Cmd+Shift+P` on macOS or `Ctrl+Shift+P` on Windows/Linux).
+2.  Search for and run the **Chat: Install Plugin From Source** command.
+3.  Paste in our repository URL: `https://github.com/ChromeDevTools/chrome-devtools-mcp`
+
+That's it! Your agent is now supercharged with Chrome DevTools capabilities.
+
+---
+
+**Install as an MCP Server (MCP only)**
+
+**Click the button to install:**
+
+[<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="Install in VS Code">](https://vscode.dev/redirect/mcp/install?name=io.github.ChromeDevTools%2Fchrome-devtools-mcp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22chrome-devtools-mcp%22%5D%2C%22env%22%3A%7B%7D%7D)
+
+[<img src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5" alt="Install in VS Code Insiders">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522io.github.ChromeDevTools%252Fchrome-devtools-mcp%2522%252C%2522config%2522%253A%257B%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522chrome-devtools-mcp%2522%255D%252C%2522env%2522%253A%257B%257D%257D%257D)
+
+**Or install manually:**
+
+Follow the VS Code [MCP configuration guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server) using the standard config from above, or use the CLI:
+
+For macOS and Linux:
+
+```bash
+code --add-mcp '{"name":"io.github.ChromeDevTools/chrome-devtools-mcp","command":"npx","args":["-y","chrome-devtools-mcp"],"env":{}}'
+```
+
+For Windows (PowerShell):
+
+```powershell
+code --add-mcp '{"""name""":"""io.github.ChromeDevTools/chrome-devtools-mcp""","""command""":"""npx""","""args""":["""-y""","""chrome-devtools-mcp"""]}'
+```
+
+</details>
+
+<details>
+  <summary>Cursor</summary>
+
+**Click the button to install:**
+
+[<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor">](https://cursor.com/en/install-mcp?name=chrome-devtools&config=eyJjb21tYW5kIjoibnB4IC15IGNocm9tZS1kZXZ0b29scy1tY3BAbGF0ZXN0In0%3D)
+
+**Or install manually:**
+
+Go to `Cursor Settings` -> `MCP` -> `New MCP Server`. Use the config provided above.
+
+</details>
+
+<details>
+  <summary>Factory CLI</summary>
+Use the Factory CLI to add the Chrome DevTools MCP server (<a href="https://docs.factory.ai/cli/configuration/mcp">guide</a>):
+
+```bash
+droid mcp add chrome-devtools "npx -y chrome-devtools-mcp@latest"
+```
+
+</details>
+
+<details>
+  <summary>Gemini CLI</summary>
+Install the Chrome DevTools MCP server using the Gemini CLI.
+
+**Project wide:**
+
+```bash
+# Either MCP only:
+gemini mcp add chrome-devtools npx chrome-devtools-mcp@latest
+# Or as a Gemini extension (MCP+Skills):
+gemini extensions install --auto-update https://github.com/ChromeDevTools/chrome-devtools-mcp
+```
+
+**Globally:**
+
+```bash
+gemini mcp add -s user chrome-devtools npx chrome-devtools-mcp@latest
+```
+
+Alternatively, follow the <a href="https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md#how-to-set-up-your-mcp-server">MCP guide</a> and use the standard config from above.
+
+</details>
+
+<details>
+  <summary>Gemini Code Assist</summary>
+  Follow the <a href="https://cloud.google.com/gemini/docs/codeassist/use-agentic-chat-pair-programmer#configure-mcp-servers">configure MCP guide</a>
+  using the standard config from above.
+</details>
+
+<details>
+  <summary>JetBrains AI Assistant & Junie</summary>
+
+Go to `Settings | Tools | AI Assistant | Model Context Protocol (MCP)` -> `Add`. Use the config provided above.
+The same way chrome-devtools-mcp can be configured for JetBrains Junie in `Settings | Tools | Junie | MCP Settings` -> `Add`. Use the config provided above.
+
+</details>
+
+<details>
+  <summary>Kiro</summary>
+
+In **Kiro Settings**, go to `Configure MCP` > `Open Workspace or User MCP Config` > Use the configuration snippet provided above.
+
+Or, from the IDE **Activity Bar** > `Kiro` > `MCP Servers` > `Click Open MCP Config`. Use the configuration snippet provided above.
+
+</details>
+
+<details>
+  <summary>Katalon Studio</summary>
+
+The Chrome DevTools MCP server can be used with <a href="https://docs.katalon.com/katalon-studio/studioassist/mcp-servers/setting-up-chrome-devtools-mcp-server-for-studioassist">Katalon StudioAssist</a> via an MCP proxy.
+
+**Step 1:** Install the MCP proxy by following the <a href="https://docs.katalon.com/katalon-studio/studioassist/mcp-servers/setting-up-mcp-proxy-for-stdio-mcp-servers">MCP proxy setup guide</a>.
+
+**Step 2:** Start the Chrome DevTools MCP server with the proxy:
+
+```bash
+mcp-proxy --transport streamablehttp --port 8080 -- npx -y chrome-devtools-mcp@latest
+```
+
+**Note:** You may need to pick another port if 8080 is already in use.
+
+**Step 3:** In Katalon Studio, add the server to StudioAssist with the following settings:
+
+- **Connection URL:** `http://127.0.0.1:8080/mcp`
+- **Transport type:** `HTTP`
+
+Once connected, the Chrome DevTools MCP tools will be available in StudioAssist.
+
+</details>
+
+<details>
+  <summary>Mistral Vibe</summary>
+
+Add in ~/.vibe/config.toml:
+
+```toml
+[[mcp_servers]]
+name = "chrome-devtools"
+transport = "stdio"
+command = "npx"
+args = ["chrome-devtools-mcp@latest"]
+```
+
+</details>
+
+<details>
+  <summary>OpenCode</summary>
+
+Add the following configuration to your `opencode.json` file. If you don't have one, create it at `~/.config/opencode/opencode.json` (<a href="https://opencode.ai/docs/mcp-servers">guide</a>):
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "chrome-devtools": {
+      "type": "local",
+      "command": ["npx", "-y", "chrome-devtools-mcp@latest"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+  <summary>Qoder</summary>
+
+In **Qoder Settings**, go to `MCP Server` > `+ Add` > Use the configuration snippet provided above.
+
+Alternatively, follow the <a href="https://docs.qoder.com/user-guide/chat/model-context-protocol">MCP guide</a> and use the standard config from above.
+
+</details>
+
+<details>
+  <summary>Qoder CLI</summary>
+
+Install the Chrome DevTools MCP server using the Qoder CLI (<a href="https://docs.qoder.com/cli/using-cli#mcp-servers">guide</a>):
+
+**Project wide:**
+
+```bash
+qodercli mcp add chrome-devtools -- npx chrome-devtools-mcp@latest
+```
+
+**Globally:**
+
+```bash
+qodercli mcp add -s user chrome-devtools -- npx chrome-devtools-mcp@latest
+```
+
+</details>
+
+<details>
+  <summary>Visual Studio</summary>
+
+**Click the button to install:**
+
+[<img src="https://img.shields.io/badge/Visual_Studio-Install-C16FDE?logo=visualstudio&logoColor=white" alt="Install in Visual Studio">](https://vs-open.link/mcp-install?%7B%22name%22%3A%22chrome-devtools%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22chrome-devtools-mcp%40latest%22%5D%7D)
+
+</details>
+
+<details>
+  <summary>Warp</summary>
+
+Go to `Settings | AI | Manage MCP Servers` -> `+ Add` to [add an MCP Server](https://docs.warp.dev/knowledge-and-collaboration/mcp#adding-an-mcp-server). Use the config provided above.
+
+</details>
+
+<details>
+  <summary>Windsurf</summary>
+  Follow the <a href="https://docs.windsurf.com/windsurf/cascade/mcp#mcp-config-json">configure MCP guide</a>
+  using the standard config from above.
+</details>
+
+### Your first prompt
+
+Enter the following prompt in your MCP Client to check if everything is working:
+
+```
+Check the performance of https://example.com
+```
+
+Your MCP client should open Brave (or attach to the running instance) and record a performance trace.
+
+> [!NOTE]
+> The MCP server will start the browser automatically once the MCP client uses a tool that requires a running browser instance. Connecting to the Brave DevTools MCP server on its own will not automatically start the browser.
+
+## Tools
+
+If you run into any issues, checkout our [troubleshooting guide](./docs/troubleshooting.md).
+
+<!-- BEGIN AUTO GENERATED TOOLS -->
+
+- **Input automation** (9 tools)
+  - [`click`](docs/tool-reference.md#click)
+  - [`drag`](docs/tool-reference.md#drag)
+  - [`fill`](docs/tool-reference.md#fill)
+  - [`fill_form`](docs/tool-reference.md#fill_form)
+  - [`handle_dialog`](docs/tool-reference.md#handle_dialog)
+  - [`hover`](docs/tool-reference.md#hover)
+  - [`press_key`](docs/tool-reference.md#press_key)
+  - [`type_text`](docs/tool-reference.md#type_text)
+  - [`upload_file`](docs/tool-reference.md#upload_file)
+- **Navigation automation** (6 tools)
+  - [`close_page`](docs/tool-reference.md#close_page)
+  - [`list_pages`](docs/tool-reference.md#list_pages)
+  - [`navigate_page`](docs/tool-reference.md#navigate_page)
+  - [`new_page`](docs/tool-reference.md#new_page)
+  - [`select_page`](docs/tool-reference.md#select_page)
+  - [`wait_for`](docs/tool-reference.md#wait_for)
+- **Emulation** (2 tools)
+  - [`emulate`](docs/tool-reference.md#emulate)
+  - [`resize_page`](docs/tool-reference.md#resize_page)
+- **Performance** (4 tools)
+  - [`performance_analyze_insight`](docs/tool-reference.md#performance_analyze_insight)
+  - [`performance_start_trace`](docs/tool-reference.md#performance_start_trace)
+  - [`performance_stop_trace`](docs/tool-reference.md#performance_stop_trace)
+  - [`take_memory_snapshot`](docs/tool-reference.md#take_memory_snapshot)
+- **Network** (2 tools)
+  - [`get_network_request`](docs/tool-reference.md#get_network_request)
+  - [`list_network_requests`](docs/tool-reference.md#list_network_requests)
+- **Debugging** (6 tools)
+  - [`evaluate_script`](docs/tool-reference.md#evaluate_script)
+  - [`get_console_message`](docs/tool-reference.md#get_console_message)
+  - [`lighthouse_audit`](docs/tool-reference.md#lighthouse_audit)
+  - [`list_console_messages`](docs/tool-reference.md#list_console_messages)
+  - [`take_screenshot`](docs/tool-reference.md#take_screenshot)
+  - [`take_snapshot`](docs/tool-reference.md#take_snapshot)
+
+<!-- END AUTO GENERATED TOOLS -->
+
+## Configuration
+
+The Brave DevTools MCP server supports the following configuration options:
+
+<!-- BEGIN AUTO GENERATED OPTIONS -->
+
+- **`--autoConnect`/ `--auto-connect`**
+  If specified, automatically connects to a browser (Chrome 144+) running locally from the user data directory identified by the channel param (default channel is stable). Requires the remote debugging server to be started in the Chrome instance via chrome://inspect/#remote-debugging.
+  - **Type:** boolean
+  - **Default:** `false`
+
+- **`--browserUrl`/ `--browser-url`, `-u`**
+  Connect to a running, debuggable Chrome instance (e.g. `http://127.0.0.1:9222`). For more details see: https://github.com/ChromeDevTools/chrome-devtools-mcp#connecting-to-a-running-chrome-instance.
+  - **Type:** string
+
+- **`--wsEndpoint`/ `--ws-endpoint`, `-w`**
+  WebSocket endpoint to connect to a running Chrome instance (e.g., ws://127.0.0.1:9222/devtools/browser/<id>). Alternative to --browserUrl.
+  - **Type:** string
+
+- **`--wsHeaders`/ `--ws-headers`**
+  Custom headers for WebSocket connection in JSON format (e.g., '{"Authorization":"Bearer token"}'). Only works with --wsEndpoint.
+  - **Type:** string
+
+- **`--headless`**
+  Whether to run in headless (no UI) mode.
+  - **Type:** boolean
+  - **Default:** `false`
+
+- **`--executablePath`/ `--executable-path`, `-e`**
+  Path to custom Chrome executable.
+  - **Type:** string
+
+- **`--isolated`**
+  If specified, creates a temporary user-data-dir that is automatically cleaned up after the browser is closed. Defaults to false.
+  - **Type:** boolean
+
+- **`--userDataDir`/ `--user-data-dir`**
+  Path to the user data directory for Chrome. Default is $HOME/.cache/chrome-devtools-mcp/chrome-profile$CHANNEL_SUFFIX_IF_NON_STABLE
+  - **Type:** string
+
+- **`--channel`**
+  Specify a different Chrome channel that should be used. The default is the stable channel version.
+  - **Type:** string
+  - **Choices:** `stable`, `canary`, `beta`, `dev`
+
+- **`--logFile`/ `--log-file`**
+  Path to a file to write debug logs to. Set the env variable `DEBUG` to `*` to enable verbose logs. Useful for submitting bug reports.
+  - **Type:** string
+
+- **`--viewport`**
+  Initial viewport size for the Chrome instances started by the server. For example, `1280x720`. In headless mode, max size is 3840x2160px.
+  - **Type:** string
+
+- **`--proxyServer`/ `--proxy-server`**
+  Proxy server configuration for Chrome passed as --proxy-server when launching the browser. See https://www.chromium.org/developers/design-documents/network-settings/ for details.
+  - **Type:** string
+
+- **`--acceptInsecureCerts`/ `--accept-insecure-certs`**
+  If enabled, ignores errors relative to self-signed and expired certificates. Use with caution.
+  - **Type:** boolean
+
+- **`--experimentalVision`/ `--experimental-vision`**
+  Whether to enable coordinate-based tools such as click_at(x,y). Usually requires a computer-use model able to produce accurate coordinates by looking at screenshots.
+  - **Type:** boolean
+
+- **`--experimentalScreencast`/ `--experimental-screencast`**
+  Exposes experimental screencast tools (requires ffmpeg). Install ffmpeg https://www.ffmpeg.org/download.html and ensure it is available in the MCP server PATH.
+  - **Type:** boolean
+
+- **`--chromeArg`/ `--chrome-arg`**
+  Additional arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.
+  - **Type:** array
+
+- **`--ignoreDefaultChromeArg`/ `--ignore-default-chrome-arg`**
+  Explicitly disable default arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.
+  - **Type:** array
+
+- **`--categoryEmulation`/ `--category-emulation`**
+  Set to false to exclude tools related to emulation.
+  - **Type:** boolean
+  - **Default:** `true`
+
+- **`--categoryPerformance`/ `--category-performance`**
+  Set to false to exclude tools related to performance.
+  - **Type:** boolean
+  - **Default:** `true`
+
+- **`--categoryNetwork`/ `--category-network`**
+  Set to false to exclude tools related to network.
+  - **Type:** boolean
+  - **Default:** `true`
+
+- **`--performanceCrux`/ `--performance-crux`**
+  Set to false to disable sending URLs from performance traces to CrUX API to get field performance data.
+  - **Type:** boolean
+  - **Default:** `true`
+
+- **`--usageStatistics`/ `--usage-statistics`**
+  Set to false to opt-out of usage statistics collection. Google collects usage data to improve the tool, handled under the Google Privacy Policy (https://policies.google.com/privacy). This is independent from Chrome browser metrics. Disabled if `CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS` or `CI` env variables are set.
+  - **Type:** boolean
+  - **Default:** `true`
+
+- **`--slim`**
+  Exposes a "slim" set of 3 tools covering navigation, script execution and screenshots only. Useful for basic browser tasks.
+  - **Type:** boolean
+
+<!-- END AUTO GENERATED OPTIONS -->
+
+Pass them via the `args` property in the JSON configuration. For example:
+
+```json
+{
+  "mcpServers": {
+    "chrome-devtools": {
+      "command": "npx",
+      "args": [
+        "chrome-devtools-mcp@latest",
+        "--channel=canary",
+        "--headless=true",
+        "--isolated=true"
+      ]
+    }
+  }
+}
+```
+
+### Connecting via WebSocket with custom headers
+
+You can connect directly to a Chrome WebSocket endpoint and include custom headers (e.g., for authentication):
+
+```json
+{
+  "mcpServers": {
+    "chrome-devtools": {
+      "command": "npx",
+      "args": [
+        "chrome-devtools-mcp@latest",
+        "--wsEndpoint=ws://127.0.0.1:9222/devtools/browser/<id>",
+        "--wsHeaders={\"Authorization\":\"Bearer YOUR_TOKEN\"}"
+      ]
+    }
+  }
+}
+```
+
+To get the WebSocket endpoint from a running Chrome instance, visit `http://127.0.0.1:9222/json/version` and look for the `webSocketDebuggerUrl` field.
+
+You can also run `npx chrome-devtools-mcp@latest --help` to see all available configuration options.
+
+## Concepts
+
+### User data directory
+
+`brave-devtools-mcp` starts a Brave release channel instance using the following user
+data directory:
+
+- Linux / macOS: `$HOME/.cache/brave-devtools-mcp/brave-profile-$CHANNEL`
+- Windows: `%HOMEPATH%/.cache/brave-devtools-mcp/brave-profile-$CHANNEL`
+
+The user data directory is not cleared between runs and shared across
+all instances of `brave-devtools-mcp`. Set the `isolated` option to `true`
+to use a temporary user data dir instead which will be cleared automatically after
+the browser is closed.
+
+### Connecting to a running Brave instance
+
+See [Mode B: Attach to your existing Brave window](#mode-b-attach-to-your-existing-brave-window) in the Setup section above.
+
+For VM-to-host port forwarding issues, see [`docs/troubleshooting.md`](./docs/troubleshooting.md#remote-debugging-between-virtual-machine-vm-and-host-fails).
+
+### Debugging on Android
+
+Please consult [these instructions](./docs/debugging-android.md) (originally written for Chrome, but applicable to any Chromium browser).
+
+## Known limitations
+
+See [Troubleshooting](./docs/troubleshooting.md).