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:

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

DOM Inspection

mcp_chrome_get_document - Get the page DOM structure

Example usage:

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:

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

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:

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

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

mcp_chrome_clear_console - Clear console messages

Example usage:

mcp_chrome_clear_console();

Network Monitoring

mcp_chrome_get_network_logs - Get network request logs

Example usage:

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:

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

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

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:

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

mcp_chrome_stop_profiling - Stop CPU profiling and get results

Example usage:

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

mcp_chrome_get_metrics - Get performance metrics

Example usage:

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:

// 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:
```
nx run lexico:develop
```

Navigate to application:

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

Check console for errors:

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

Inspect specific element:

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

Execute test code:

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

Performance Analysis

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

Perform actions:

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

Stop and analyze:

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

Get metrics:

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

Visual Regression Testing

Set consistent viewport:

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

Navigate to page:

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

Take screenshot:

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

Compare with baseline:

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

Mobile Testing

Set mobile viewport:

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

Set mobile user agent:

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:

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

Network Analysis

Navigate and monitor:

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

Get network logs:

const requests = mcp_chrome_get_network_logs();

Analyze requests:

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:

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

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

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

// 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

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

// 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