chrome-devtools-mcp 0.17.3 → 0.18.0

package/README.md

@@ -73,6 +73,21 @@ Add the following config to your MCP client:
 > [!NOTE]  
 > Using `chrome-devtools-mcp@latest` ensures that your MCP client will always use the latest version of the Chrome DevTools MCP server.
 
+If you are intersted in doing only basic browser tasks, use the `--slim` mode:
+
+```json
+{
+  "mcpServers": {
+    "chrome-devtools": {
+      "command": "npx",
+      "args": ["-y", "chrome-devtools-mcp@latest", "--slim", "--headless"]
+    }
+  }
+}
+```
+
+See [Slim tool reference](./docs/slim-tool-reference.md).
+
 ### MCP Client configuration
 
 <details>
@@ -399,7 +414,7 @@ If you run into any issues, checkout our [troubleshooting guide](./docs/troubles
 
 <!-- BEGIN AUTO GENERATED TOOLS -->
 
-- **Input automation** (8 tools)
+- **Input automation** (9 tools)
   - [`click`](docs/tool-reference.md#click)
   - [`drag`](docs/tool-reference.md#drag)
   - [`fill`](docs/tool-reference.md#fill)
@@ -407,6 +422,7 @@ If you run into any issues, checkout our [troubleshooting guide](./docs/troubles
   - [`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)
@@ -418,10 +434,11 @@ If you run into any issues, checkout our [troubleshooting guide](./docs/troubles
 - **Emulation** (2 tools)
   - [`emulate`](docs/tool-reference.md#emulate)
   - [`resize_page`](docs/tool-reference.md#resize_page)
-- **Performance** (3 tools)
+- **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)
@@ -495,6 +512,10 @@ The Chrome DevTools MCP server supports the following configuration option:
   If enabled, ignores errors relative to self-signed and expired certificates. Use with caution.
   - **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
@@ -528,6 +549,10 @@ The Chrome DevTools MCP server supports the following configuration option:
   - **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:

package/build/src/McpContext.js

@@ -9,6 +9,7 @@ import path from 'node:path';
 import { extractUrlLikeFromDevToolsTitle, UniverseManager, urlsEqual, } from './DevtoolsUtils.js';
 import { NetworkCollector, ConsoleCollector } from './PageCollector.js';
 import { Locator } from './third_party/index.js';
+import { PredefinedNetworkConditions } from './third_party/index.js';
 import { listPages } from './tools/pages.js';
 import { takeSnapshot } from './tools/snapshot.js';
 import { CLOSE_PAGE_ERROR } from './tools/ToolDefinition.js';
@@ -44,23 +45,24 @@ function getExtensionFromMimeType(mimeType) {
 export class McpContext {
     browser;
     logger;
-    // The most recent page state.
+    // Maps LLM-provided isolatedContext name → Puppeteer BrowserContext.
+    #isolatedContexts = new Map();
+    // Reverse lookup: Page → isolatedContext name (for snapshot labeling).
+    // WeakMap so closed pages are garbage-collected automatically.
+    #pageToIsolatedContextName = new WeakMap();
+    // Auto-generated name counter for when no name is provided.
+    #nextIsolatedContextId = 1;
     #pages = [];
     #pageToDevToolsPage = new Map();
     #selectedPage;
-    // The most recent snapshot.
     #textSnapshot = null;
     #networkCollector;
     #consoleCollector;
     #devtoolsUniverseManager;
     #extensionRegistry = new ExtensionRegistry();
     #isRunningTrace = false;
-    #networkConditionsMap = new WeakMap();
-    #cpuThrottlingRateMap = new WeakMap();
-    #geolocationMap = new WeakMap();
-    #viewportMap = new WeakMap();
-    #userAgentMap = new WeakMap();
-    #colorSchemeMap = new WeakMap();
+    #screenRecorderData = null;
+    #emulationSettingsMap = new WeakMap();
     #dialog;
     #pageIdMap = new WeakMap();
     #nextPageId = 1;
@@ -100,6 +102,10 @@ export class McpContext {
         this.#networkCollector.dispose();
         this.#consoleCollector.dispose();
         this.#devtoolsUniverseManager.dispose();
+        // Isolated contexts are intentionally not closed here.
+        // Either the entire browser will be closed or we disconnect
+        // without destroying browser state.
+        this.#isolatedContexts.clear();
     }
     static async from(browser, logger, opts, 
     /* Let tests use unbundled Locator class to avoid overly strict checks within puppeteer that fail when mixing bundled and unbundled class instances */
@@ -163,8 +169,20 @@ export class McpContext {
     getConsoleMessageById(id) {
         return this.#consoleCollector.getById(this.getSelectedPage(), id);
     }
-    async newPage(background) {
-        const page = await this.browser.newPage({ background });
+    async newPage(background, isolatedContextName) {
+        let page;
+        if (isolatedContextName !== undefined) {
+            let ctx = this.#isolatedContexts.get(isolatedContextName);
+            if (!ctx) {
+                ctx = await this.browser.createBrowserContext();
+                this.#isolatedContexts.set(isolatedContextName, ctx);
+            }
+            page = await ctx.newPage();
+            this.#pageToIsolatedContextName.set(page, isolatedContextName);
+        }
+        else {
+            page = await this.browser.newPage({ background });
+        }
         await this.createPagesSnapshot();
         this.selectPage(page);
         this.#networkCollector.addPage(page);
@@ -177,84 +195,133 @@ export class McpContext {
         }
         const page = this.getPageById(pageId);
         await page.close({ runBeforeUnload: false });
+        this.#pageToIsolatedContextName.delete(page);
     }
     getNetworkRequestById(reqid) {
         return this.#networkCollector.getById(this.getSelectedPage(), reqid);
     }
-    setNetworkConditions(conditions) {
+    async emulate(options) {
         const page = this.getSelectedPage();
-        if (conditions === null) {
-            this.#networkConditionsMap.delete(page);
+        const currentSettings = this.#emulationSettingsMap.get(page) ?? {};
+        const newSettings = { ...currentSettings };
+        let timeoutsNeedUpdate = false;
+        if (options.networkConditions !== undefined) {
+            timeoutsNeedUpdate = true;
+            if (options.networkConditions === null ||
+                options.networkConditions === 'No emulation') {
+                await page.emulateNetworkConditions(null);
+                delete newSettings.networkConditions;
+            }
+            else if (options.networkConditions === 'Offline') {
+                await page.emulateNetworkConditions({
+                    offline: true,
+                    download: 0,
+                    upload: 0,
+                    latency: 0,
+                });
+                newSettings.networkConditions = 'Offline';
+            }
+            else if (options.networkConditions in PredefinedNetworkConditions) {
+                const networkCondition = PredefinedNetworkConditions[options.networkConditions];
+                await page.emulateNetworkConditions(networkCondition);
+                newSettings.networkConditions = options.networkConditions;
+            }
+        }
+        if (options.cpuThrottlingRate !== undefined) {
+            timeoutsNeedUpdate = true;
+            if (options.cpuThrottlingRate === null) {
+                await page.emulateCPUThrottling(1);
+                delete newSettings.cpuThrottlingRate;
+            }
+            else {
+                await page.emulateCPUThrottling(options.cpuThrottlingRate);
+                newSettings.cpuThrottlingRate = options.cpuThrottlingRate;
+            }
+        }
+        if (options.geolocation !== undefined) {
+            if (options.geolocation === null) {
+                await page.setGeolocation({ latitude: 0, longitude: 0 });
+                delete newSettings.geolocation;
+            }
+            else {
+                await page.setGeolocation(options.geolocation);
+                newSettings.geolocation = options.geolocation;
+            }
+        }
+        if (options.userAgent !== undefined) {
+            if (options.userAgent === null) {
+                await page.setUserAgent({ userAgent: undefined });
+                delete newSettings.userAgent;
+            }
+            else {
+                await page.setUserAgent({ userAgent: options.userAgent });
+                newSettings.userAgent = options.userAgent;
+            }
+        }
+        if (options.colorScheme !== undefined) {
+            if (options.colorScheme === null || options.colorScheme === 'auto') {
+                await page.emulateMediaFeatures([
+                    { name: 'prefers-color-scheme', value: '' },
+                ]);
+                delete newSettings.colorScheme;
+            }
+            else {
+                await page.emulateMediaFeatures([
+                    { name: 'prefers-color-scheme', value: options.colorScheme },
+                ]);
+                newSettings.colorScheme = options.colorScheme;
+            }
+        }
+        if (options.viewport !== undefined) {
+            if (options.viewport === null) {
+                await page.setViewport(null);
+                delete newSettings.viewport;
+            }
+            else {
+                const defaults = {
+                    deviceScaleFactor: 1,
+                    isMobile: false,
+                    hasTouch: false,
+                    isLandscape: false,
+                };
+                const viewport = { ...defaults, ...options.viewport };
+                await page.setViewport(viewport);
+                newSettings.viewport = viewport;
+            }
+        }
+        if (Object.keys(newSettings).length) {
+            this.#emulationSettingsMap.set(page, newSettings);
         }
         else {
-            this.#networkConditionsMap.set(page, conditions);
+            this.#emulationSettingsMap.delete(page);
+        }
+        if (timeoutsNeedUpdate) {
+            this.#updateSelectedPageTimeouts();
         }
-        this.#updateSelectedPageTimeouts();
     }
     getNetworkConditions() {
         const page = this.getSelectedPage();
-        return this.#networkConditionsMap.get(page) ?? null;
-    }
-    setCpuThrottlingRate(rate) {
-        const page = this.getSelectedPage();
-        this.#cpuThrottlingRateMap.set(page, rate);
-        this.#updateSelectedPageTimeouts();
+        return this.#emulationSettingsMap.get(page)?.networkConditions ?? null;
     }
     getCpuThrottlingRate() {
         const page = this.getSelectedPage();
-        return this.#cpuThrottlingRateMap.get(page) ?? 1;
-    }
-    setGeolocation(geolocation) {
-        const page = this.getSelectedPage();
-        if (geolocation === null) {
-            this.#geolocationMap.delete(page);
-        }
-        else {
-            this.#geolocationMap.set(page, geolocation);
-        }
+        return this.#emulationSettingsMap.get(page)?.cpuThrottlingRate ?? 1;
     }
     getGeolocation() {
         const page = this.getSelectedPage();
-        return this.#geolocationMap.get(page) ?? null;
-    }
-    setViewport(viewport) {
-        const page = this.getSelectedPage();
-        if (viewport === null) {
-            this.#viewportMap.delete(page);
-        }
-        else {
-            this.#viewportMap.set(page, viewport);
-        }
+        return this.#emulationSettingsMap.get(page)?.geolocation ?? null;
     }
     getViewport() {
         const page = this.getSelectedPage();
-        return this.#viewportMap.get(page) ?? null;
-    }
-    setUserAgent(userAgent) {
-        const page = this.getSelectedPage();
-        if (userAgent === null) {
-            this.#userAgentMap.delete(page);
-        }
-        else {
-            this.#userAgentMap.set(page, userAgent);
-        }
+        return this.#emulationSettingsMap.get(page)?.viewport ?? null;
     }
     getUserAgent() {
         const page = this.getSelectedPage();
-        return this.#userAgentMap.get(page) ?? null;
-    }
-    setColorScheme(scheme) {
-        const page = this.getSelectedPage();
-        if (scheme === null) {
-            this.#colorSchemeMap.delete(page);
-        }
-        else {
-            this.#colorSchemeMap.set(page, scheme);
-        }
+        return this.#emulationSettingsMap.get(page)?.userAgent ?? null;
     }
     getColorScheme() {
         const page = this.getSelectedPage();
-        return this.#colorSchemeMap.get(page) ?? null;
+        return this.#emulationSettingsMap.get(page)?.colorScheme ?? null;
     }
     setIsRunningPerformanceTrace(x) {
         this.#isRunningTrace = x;
@@ -262,6 +329,12 @@ export class McpContext {
     isRunningPerformanceTrace() {
         return this.#isRunningTrace;
     }
+    getScreenRecorder() {
+        return this.#screenRecorderData;
+    }
+    setScreenRecorder(data) {
+        this.#screenRecorderData = data;
+    }
     isCruxEnabled() {
         return this.#options.performanceCrux;
     }
@@ -353,19 +426,14 @@ export class McpContext {
             });
         }
     }
-    /**
-     * Creates a snapshot of the pages.
-     */
     async createPagesSnapshot() {
-        const allPages = await this.browser.pages(this.#options.experimentalIncludeAllPages);
+        const allPages = await this.#getAllPages();
         for (const page of allPages) {
             if (!this.#pageIdMap.has(page)) {
                 this.#pageIdMap.set(page, this.#nextPageId++);
             }
         }
         this.#pages = allPages.filter(page => {
-            // If we allow debugging DevTools windows, return all pages.
-            // If we are in regular mode, the user should only see non-DevTools page.
             return (this.#options.experimentalDevToolsDebugging ||
                 !page.url().startsWith('devtools://'));
         });
@@ -376,9 +444,37 @@ export class McpContext {
         await this.detectOpenDevToolsWindows();
         return this.#pages;
     }
+    async #getAllPages() {
+        const defaultCtx = this.browser.defaultBrowserContext();
+        const allPages = await this.browser.pages(this.#options.experimentalIncludeAllPages);
+        // Build a reverse lookup from BrowserContext instance → name.
+        const contextToName = new Map();
+        for (const [name, ctx] of this.#isolatedContexts) {
+            contextToName.set(ctx, name);
+        }
+        // Auto-discover BrowserContexts not in our mapping (e.g., externally
+        // created incognito contexts) and assign generated names.
+        const knownContexts = new Set(this.#isolatedContexts.values());
+        for (const ctx of this.browser.browserContexts()) {
+            if (ctx !== defaultCtx && !ctx.closed && !knownContexts.has(ctx)) {
+                const name = `isolated-context-${this.#nextIsolatedContextId++}`;
+                this.#isolatedContexts.set(name, ctx);
+                contextToName.set(ctx, name);
+            }
+        }
+        // Use page.browserContext() to determine each page's context membership.
+        for (const page of allPages) {
+            const ctx = page.browserContext();
+            const name = contextToName.get(ctx);
+            if (name) {
+                this.#pageToIsolatedContextName.set(page, name);
+            }
+        }
+        return allPages;
+    }
     async detectOpenDevToolsWindows() {
         this.logger('Detecting open DevTools windows');
-        const pages = await this.browser.pages(this.#options.experimentalIncludeAllPages);
+        const pages = await this.#getAllPages();
         this.#pageToDevToolsPage = new Map();
         for (const devToolsPage of pages) {
             if (devToolsPage.url().startsWith('devtools://')) {
@@ -409,6 +505,9 @@ export class McpContext {
     getPages() {
         return this.#pages;
     }
+    getIsolatedContextName(page) {
+        return this.#pageToIsolatedContextName.get(page);
+    }
     getDevToolsPage(page) {
         return this.#pageToDevToolsPage.get(page);
     }
@@ -560,10 +659,10 @@ export class McpContext {
     waitForTextOnPage(text, timeout) {
         const page = this.getSelectedPage();
         const frames = page.frames();
-        let locator = this.#locatorClass.race(frames.flatMap(frame => [
-            frame.locator(`aria/${text}`),
-            frame.locator(`text/${text}`),
-        ]));
+        let locator = this.#locatorClass.race(frames.flatMap(frame => text.flatMap(value => [
+            frame.locator(`aria/${value}`),
+            frame.locator(`text/${value}`),
+        ])));
         if (timeout) {
             locator = locator.setTimeout(timeout);
         }
@@ -583,7 +682,8 @@ export class McpContext {
                 },
             };
         });
-        await this.#networkCollector.init(await this.browser.pages());
+        const pages = await this.#getAllPages();
+        await this.#networkCollector.init(pages);
     }
     async installExtension(extensionPath) {
         const id = await this.browser.installExtension(extensionPath);

package/build/src/McpResponse.js

@@ -325,15 +325,24 @@ Call ${handleDialog.name} to handle it before continuing.`);
         if (this.#includePages) {
             const parts = [`## Pages`];
             for (const page of context.getPages()) {
-                parts.push(`${context.getPageId(page)}: ${page.url()}${context.isPageSelected(page) ? ' [selected]' : ''}`);
+                const isolatedContextName = context.getIsolatedContextName(page);
+                const contextLabel = isolatedContextName
+                    ? ` isolatedContext=${isolatedContextName}`
+                    : '';
+                parts.push(`${context.getPageId(page)}: ${page.url()}${context.isPageSelected(page) ? ' [selected]' : ''}${contextLabel}`);
             }
             response.push(...parts);
             structuredContent.pages = context.getPages().map(page => {
-                return {
+                const isolatedContextName = context.getIsolatedContextName(page);
+                const entry = {
                     id: context.getPageId(page),
                     url: page.url(),
                     selected: context.isPageSelected(page),
                 };
+                if (isolatedContextName) {
+                    entry.isolatedContext = isolatedContextName;
+                }
+                return entry;
             });
         }
         if (this.#tabId) {

package/build/src/SlimMcpResponse.js

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { McpResponse } from './McpResponse.js';
+export class SlimMcpResponse extends McpResponse {
+    async handle(_toolName, _context) {
+        const text = {
+            type: 'text',
+            text: this.responseLines.join('\n'),
+        };
+        return {
+            content: [text],
+            structuredContent: text,
+        };
+    }
+}

package/build/src/browser.js

@@ -3,6 +3,7 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+import { execSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -103,6 +104,22 @@ export async function ensureBrowserConnected(options) {
     logger('Connected Puppeteer');
     return browser;
 }
+export function detectDisplay() {
+    // Only detect display on Linux/UNIX.
+    if (os.platform() === 'win32' || os.platform() === 'darwin') {
+        return;
+    }
+    if (!process.env['DISPLAY']) {
+        try {
+            const result = execSync(`ps -u $(id -u) -o pid= | xargs -I{} cat /proc/{}/environ 2>/dev/null | tr '\\0' '\\n' | grep -m1 '^DISPLAY=' | cut -d= -f2`);
+            const display = result.toString('utf8').trim();
+            process.env['DISPLAY'] = display;
+        }
+        catch {
+            // no-op
+        }
+    }
+}
 export async function launch(options) {
     const { channel, executablePath, headless, isolated } = options;
     const profileDirName = channel && channel !== 'stable'
@@ -133,6 +150,9 @@ export async function launch(options) {
                 ? `chrome-${channel}`
                 : 'chrome';
     }
+    if (!headless) {
+        detectDisplay();
+    }
     try {
         const browser = await puppeteer.launch({
             channel: puppeteerChannel,

package/build/src/cli.js

@@ -159,6 +159,10 @@ export const cliOptions = {
         describe: 'Whether to enable interoperability tools',
         hidden: true,
     },
+    experimentalScreencast: {
+        type: 'boolean',
+        describe: 'Exposes experimental screencast tools (requires ffmpeg). Install ffmpeg https://www.ffmpeg.org/download.html and ensure it is available in the MCP server PATH.',
+    },
     chromeArg: {
         type: 'array',
         describe: 'Additional arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.',
@@ -213,6 +217,10 @@ export const cliOptions = {
         hidden: true,
         describe: 'Include watchdog PID in Clearcut request headers (for testing).',
     },
+    slim: {
+        type: 'boolean',
+        describe: 'Exposes a "slim" set of 3 tools covering navigation, script execution and screenshots only. Useful for basic browser tasks.',
+    },
 };
 export function parseArguments(version, argv = process.argv) {
     const yargsInstance = yargs(hideBin(argv))
@@ -286,6 +294,10 @@ export function parseArguments(version, argv = process.argv) {
             '$0 --no-performance-crux',
             'Disable CrUX (field data) integration in performance tools.',
         ],
+        [
+            '$0 --slim',
+            'Only 3 tools: navigation, JavaScript execution and screenshot',
+        ],
     ]);
     return yargsInstance
         .wrap(Math.min(120, yargsInstance.terminalWidth()))