From 300b0c4259791ddf36a2787024903e24eb1d0dde Mon Sep 17 00:00:00 2001
From: Mohamed AlWhaidi <49125190+MohamedAlwhaidi@users.noreply.github.com>
Date: Sat, 16 May 2026 09:53:31 +0300
Subject: [PATCH] docs: explain --cdp-endpoint with a manually launched real
 Chrome
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The User profile section currently covers three paths to a persistent
browser session: bundled Chromium with --user-data-dir, --isolated, and
the Chrome extension. There is no narrative coverage of the
--cdp-endpoint flow against a real Chrome the user launched themselves,
even though the flag is documented in the configuration table.

This is a frequently-asked workflow on Discord and in issues like
#347 (network capture) and #1130 (CDP port exposure) — users want MCP
to drive the same Chrome they already have logged in, but find the
combination of `--remote-debugging-port` + a dedicated `--user-data-dir`
through trial and error.

Add a fourth subsection under "User profile" that walks through:
- the cross-platform launch command
- the MCP config snippet using `--cdp-endpoint=http://localhost:9222`
- the gotcha that the default Chrome profile cannot be used (Chrome
  blocks CDP attach on it, so a dedicated profile dir is mandatory)
---
 README.md | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/README.md b/README.md
index bbd258cae..fdb9559ca 100644
--- a/README.md
+++ b/README.md
@@ -482,6 +482,50 @@ state [here](https://playwright.dev/docs/auth).
 
 The Playwright MCP Chrome Extension allows you to connect to existing browser tabs and leverage your logged-in sessions and browser state. See [microsoft/playwright › packages/extension](https://github.com/microsoft/playwright/tree/main/packages/extension#readme) for installation and setup instructions.
 
+**Connect to your own Chrome via CDP**
+
+If you'd rather not install an extension and want Playwright MCP to drive a real Chrome that you launched yourself — with your cookies, extensions, and any extra flags — start a dedicated Chrome instance with the remote debugging port enabled and then point MCP at it via [`--cdp-endpoint`](#configuration).
+
+Launch Chrome with a **dedicated user-data-dir** (Chrome refuses CDP attach on your default profile for security, so a separate profile dir is required):
+
+```bash
+# macOS
+"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
+  --remote-debugging-port=9222 \
+  --user-data-dir="$HOME/.playwright-mcp-chrome"
+
+# Linux
+google-chrome \
+  --remote-debugging-port=9222 \
+  --user-data-dir="$HOME/.playwright-mcp-chrome"
+
+# Windows (PowerShell)
+& "C:\Program Files\Google\Chrome\Application\chrome.exe" `
+  --remote-debugging-port=9222 `
+  --user-data-dir="$env:USERPROFILE\.playwright-mcp-chrome"
+```
+
+Log in once in that window; the cookies are written to the `--user-data-dir` and persist across launches. Then configure Playwright MCP to attach over CDP instead of launching its own browser:
+
+```js
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": [
+        "@playwright/mcp@latest",
+        "--cdp-endpoint=http://localhost:9222"
+      ]
+    }
+  }
+}
+```
+
+This is useful when you want the AI assistant to drive the *same* browser you have open — for example, to inspect requests made by an SaaS you're already authenticated into without re-logging-in inside the MCP-managed profile.
+
+> [!IMPORTANT]
+> The `--user-data-dir` you pass to Chrome must **not** be your default profile (`~/Library/Application Support/Google/Chrome/Default` on macOS, etc.). Chrome blocks CDP attach on the default profile for security; you must use a dedicated directory.
+
 ### Initial state
 
 There are multiple ways to provide the initial state to the browser context or a page.