Chrome DevTools MCP Server

This skill covers using the Chrome DevTools Protocol (CDP) via MCP to debug, profile, and inspect web applications running in Chrome or Chromium browsers.

When to Use

Use Chrome DevTools MCP tools when:

•Debugging JavaScript runtime errors in lexico
•Profiling frontend performance
•Analyzing network requests and responses
•Inspecting DOM structure and CSS
•Monitoring console logs in real-time
•Taking screenshots or PDFs of pages
•Testing responsive designs
•Analyzing memory usage
•Debugging service workers or web workers

Available MCP Tools

The Chrome DevTools MCP server provides these tools (prefix: mcp_chrome_):

Page Navigation

mcp_chrome_navigate - Navigate to a URL

Parameters:

•url (required): URL to navigate to
•wait_until (optional): Wait for 'load', 'domcontentloaded', 'networkidle'

Example usage:

typescript

mcp_chrome_navigate({
  url: "http://localhost:3000",
  wait_until: "networkidle",
});

DOM Inspection

mcp_chrome_get_document - Get the page DOM structure

Example usage:

typescript

const dom = mcp_chrome_get_document();

mcp_chrome_query_selector - Find elements by CSS selector

Parameters:

•selector (required): CSS selector
•node_id (optional): Parent node to search within

Example usage:

typescript

// Find all buttons
mcp_chrome_query_selector({
  selector: "button",
});

// Find element within specific node
mcp_chrome_query_selector({
  selector: ".modal .submit-button",
  node_id: modalNodeId,
});

mcp_chrome_get_attributes - Get element attributes

Parameters:

•node_id (required): DOM node ID

Example usage:

typescript

mcp_chrome_get_attributes({
  node_id: nodeId,
});

JavaScript Execution

mcp_chrome_evaluate - Execute JavaScript in page context

Parameters:

•expression (required): JavaScript code to execute
•return_by_value (optional): Return result by value (default: true)

Example usage:

typescript

// Get page title
mcp_chrome_evaluate({
  expression: "document.title",
});

// Call function
mcp_chrome_evaluate({
  expression: "window.myFunction(42)",
});

// Return complex object
mcp_chrome_evaluate({
  expression: "JSON.stringify({ users: getUsers() })",
});

Console Monitoring

mcp_chrome_get_console_logs - Retrieve console messages

Example usage:

typescript

const logs = mcp_chrome_get_console_logs();
// Returns: Array of { level, text, timestamp, url, lineNumber }

mcp_chrome_clear_console - Clear console messages

Example usage:

typescript

mcp_chrome_clear_console();

Network Monitoring

mcp_chrome_get_network_logs - Get network request logs

Example usage:

typescript

const requests = mcp_chrome_get_network_logs();
// Returns: Array of { url, method, status, responseTime, size }

mcp_chrome_set_user_agent - Change user agent string

Parameters:

•user_agent (required): User agent string

Example usage:

typescript

// Mobile user agent
mcp_chrome_set_user_agent({
  user_agent:
    "Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15",
});

Screenshots & PDFs

mcp_chrome_screenshot - Capture page screenshot

Parameters:

•format (optional): 'png' or 'jpeg' (default: 'png')
•quality (optional): JPEG quality 0-100
•full_page (optional): Capture full scrollable page (default: false)
•clip (optional): Capture specific region { x, y, width, height }

Example usage:

typescript

// Full page screenshot
mcp_chrome_screenshot({
  format: "png",
  full_page: true,
});

// Specific element region
mcp_chrome_screenshot({
  format: "jpeg",
  quality: 90,
  clip: { x: 100, y: 100, width: 800, height: 600 },
});

mcp_chrome_pdf - Generate PDF of page

Parameters:

•landscape (optional): Landscape orientation
•print_background (optional): Include backgrounds
•scale (optional): Scale 0.1-2.0
•paper_width (optional): Paper width in inches
•paper_height (optional): Paper height in inches

Example usage:

typescript

mcp_chrome_pdf({
  landscape: false,
  print_background: true,
  scale: 1.0,
  paper_width: 8.5,
  paper_height: 11,
});

Performance Profiling

mcp_chrome_start_profiling - Start CPU profiling

Example usage:

typescript

mcp_chrome_start_profiling();
// ... perform actions ...
const profile = mcp_chrome_stop_profiling();

mcp_chrome_stop_profiling - Stop CPU profiling and get results

Example usage:

typescript

const profile = mcp_chrome_stop_profiling();
// Analyze profile.nodes, profile.samples

mcp_chrome_get_metrics - Get performance metrics

Example usage:

typescript

const metrics = mcp_chrome_get_metrics();
// Returns: { Timestamp, Documents, Frames, JSEventListeners, Nodes, ... }

Viewport & Device Emulation

mcp_chrome_set_viewport - Set viewport size

Parameters:

•width (required): Viewport width
•height (required): Viewport height
•device_scale_factor (optional): Device pixel ratio
•mobile (optional): Mobile mode

Example usage:

typescript

// Desktop viewport
mcp_chrome_set_viewport({
  width: 1920,
  height: 1080,
  device_scale_factor: 1,
});

// Mobile viewport
mcp_chrome_set_viewport({
  width: 375,
  height: 667,
  device_scale_factor: 2,
  mobile: true,
});

Workflow Patterns

Debugging lexico Application

•
Start local dev server:
bash
```
nx run lexico:develop
```

•

Navigate to application:

typescript

mcp_chrome_navigate({
  url: "http://localhost:3000",
  wait_until: "networkidle",
});

•

Check console for errors:

typescript

const logs = mcp_chrome_get_console_logs();
const errors = logs.filter((log) => log.level === "error");

•

Inspect specific element:

typescript

const nodes = mcp_chrome_query_selector({
  selector: ".search-input",
});

•

Execute test code:

typescript

mcp_chrome_evaluate({
  expression: 'window.searchWords("amor")',
});

Performance Analysis

•
Start profiling:
typescript
```
mcp_chrome_start_profiling();
```

•

Perform actions:

typescript

mcp_chrome_evaluate({
  expression: `
    document.querySelector('.search-button').click();
  `,
});

•

Stop and analyze:

typescript

const profile = mcp_chrome_stop_profiling();
// Analyze hot functions, bottlenecks

•

Get metrics:

typescript

const metrics = mcp_chrome_get_metrics();
console.log("Nodes:", metrics.Nodes);
console.log("JS Heap:", metrics.JSHeapUsedSize);

Visual Regression Testing

•

Set consistent viewport:

typescript

mcp_chrome_set_viewport({
  width: 1280,
  height: 720,
  device_scale_factor: 1,
});

•

Navigate to page:

typescript

mcp_chrome_navigate({
  url: "http://localhost:3000/word/amor",
  wait_until: "networkidle",
});

•

Take screenshot:

typescript

const screenshot = mcp_chrome_screenshot({
  format: "png",
  full_page: true,
});

•

Compare with baseline:

typescript

// Use image comparison library
const diff = compareImages(screenshot, baselineImage);

Mobile Testing

•

Set mobile viewport:

typescript

mcp_chrome_set_viewport({
  width: 375,
  height: 812, // iPhone X
  device_scale_factor: 3,
  mobile: true,
});

•

Set mobile user agent:

typescript

mcp_chrome_set_user_agent({
  user_agent:
    "Mozilla/5.0 (iPhone; CPU iPhone OS 15_0 like Mac OS X) AppleWebKit/605.1.15",
});

•

Test touch interactions:

typescript

mcp_chrome_evaluate({
  expression: `
    const button = document.querySelector('.mobile-menu');
    button.dispatchEvent(new TouchEvent('touchstart'));
  `,
});

Network Analysis

•

Navigate and monitor:

typescript

mcp_chrome_navigate({
  url: "http://localhost:3000",
});

•

Get network logs:

typescript

const requests = mcp_chrome_get_network_logs();

•

Analyze requests:

typescript

const slowRequests = requests.filter((r) => r.responseTime > 1000);
const failedRequests = requests.filter((r) => r.status >= 400);
const largeRequests = requests.filter((r) => r.size > 1000000);

Project-Specific Usage

lexico Application

Test search functionality:

typescript

// Navigate to search page
mcp_chrome_navigate({
  url: "http://localhost:3000/search",
  wait_until: "networkidle",
});

// Enter search query
mcp_chrome_evaluate({
  expression: `
    document.querySelector('input[name="q"]').value = 'amor';
    document.querySelector('form').submit();
  `,
});

// Wait for results
await new Promise((resolve) => setTimeout(resolve, 1000));

// Check results
const results = mcp_chrome_evaluate({
  expression: 'document.querySelectorAll(".search-result").length',
});

Test authentication flow:

typescript

// Navigate to login
mcp_chrome_navigate({
  url: "http://localhost:3000/login",
});

// Click OAuth provider
mcp_chrome_evaluate({
  expression: 'document.querySelector(".google-login").click()',
});

// Monitor console for auth errors
const logs = mcp_chrome_get_console_logs();
const authErrors = logs.filter(
  (log) => log.text.includes("auth") && log.level === "error",
);

Performance check:

typescript

mcp_chrome_start_profiling();

// Navigate to word detail page
mcp_chrome_navigate({
  url: "http://localhost:3000/word/amor",
  wait_until: "networkidle",
});

const profile = mcp_chrome_stop_profiling();
const metrics = mcp_chrome_get_metrics();

console.log("Page load profile:", profile);
console.log("Memory metrics:", metrics);

Common Use Cases

Debugging TypeScript Errors

typescript

// Run application
nx run lexico:develop

// Navigate to page
mcp_chrome_navigate({
  url: 'http://localhost:3000',
  wait_until: 'load'
})

// Check for errors
const logs = mcp_chrome_get_console_logs()
const errors = logs.filter(l => l.level === 'error')

for (const error of errors) {
  console.log(`Error at ${error.url}:${error.lineNumber}`)
  console.log(error.text)
}

Testing Responsive Design

typescript

const breakpoints = [
  { name: "Mobile", width: 375, height: 667 },
  { name: "Tablet", width: 768, height: 1024 },
  { name: "Desktop", width: 1920, height: 1080 },
];

for (const bp of breakpoints) {
  mcp_chrome_set_viewport({
    width: bp.width,
    height: bp.height,
  });

  mcp_chrome_navigate({
    url: "http://localhost:3000",
    wait_until: "networkidle",
  });

  const screenshot = mcp_chrome_screenshot({
    full_page: true,
  });

  // Save screenshot with name
  saveScreenshot(screenshot, `${bp.name}.png`);
}

Monitoring Memory Leaks

typescript

// Get initial metrics
mcp_chrome_navigate({ url: "http://localhost:3000" });
const initialMetrics = mcp_chrome_get_metrics();

// Perform actions multiple times
for (let i = 0; i < 100; i++) {
  mcp_chrome_evaluate({
    expression: `
      // Simulate user interaction
      document.querySelector('.search-button').click();
    `,
  });
  await new Promise((resolve) => setTimeout(resolve, 100));
}

// Get final metrics
const finalMetrics = mcp_chrome_get_metrics();

// Check for memory growth
const heapGrowth = finalMetrics.JSHeapUsedSize - initialMetrics.JSHeapUsedSize;
const nodeGrowth = finalMetrics.Nodes - initialMetrics.Nodes;

if (heapGrowth > 10000000) {
  console.warn("Potential memory leak detected");
}

Troubleshooting

Chrome not connected:

•Ensure Chrome is running with remote debugging enabled
•Check CDP endpoint is accessible
•Verify firewall settings

Viewport not applying:

•Set viewport before navigation
•Use device emulation for mobile testing
•Check if page overrides viewport with meta tags

Screenshot empty:

•Wait for page to load completely
•Check if element is visible
•Ensure viewport is set correctly

Evaluate returns undefined:

•Check if expression is valid JavaScript
•Verify return value is serializable
•Use JSON.stringify() for complex objects

Console logs missing:

•Enable console monitoring before navigation
•Check if logs are cleared by application
•Filter by log level

Best Practices

•Wait for page load before interacting
•Set viewport consistently for reproducible tests
•Clear console between test runs
•Monitor network to catch API errors
•Use query selectors instead of XPath
•Evaluate JavaScript safely with try-catch
•Take screenshots for visual verification
•Profile sparingly - impacts performance
•Clean up after debugging sessions
•Test multiple viewports for responsive design

Security Considerations

•Never run untrusted code in browser context
•Sanitize user input before evaluating
•Avoid exposing sensitive data in screenshots
•Use local development only - don't debug production
•Secure CDP endpoint if exposed remotely

mcp-chrome-devtools

Chrome DevTools MCP Server

When to Use

Available MCP Tools

Page Navigation

DOM Inspection

JavaScript Execution

Console Monitoring

Network Monitoring

Screenshots & PDFs

Performance Profiling

Viewport & Device Emulation

Workflow Patterns

Debugging lexico Application

Performance Analysis

Visual Regression Testing

Mobile Testing

Network Analysis

Project-Specific Usage

lexico Application

Common Use Cases

Debugging TypeScript Errors

Testing Responsive Design

Monitoring Memory Leaks

Troubleshooting

Best Practices

Security Considerations

Related Documentation

See Also