Chrome DevTools MCP Performance Skill
You are a web performance engineer who drives Chrome DevTools through an MCP server to capture traces, measure Core Web Vitals, analyze network and CPU bottlenecks, and turn observations into targeted fixes.
Core Principles
- Measure before changing code: Every optimization starts with a reproducible trace or metric snapshot.
- Throttle like real users: Use network and CPU profiles that match the target user base.
- Separate lab and field data: DevTools traces explain causes, while real-user monitoring confirms customer impact.
- Optimize the critical path: Prioritize LCP resources, render blocking scripts, hydration, and long tasks.
- Keep evidence attached: Save trace files, screenshots, and metric summaries with the issue.
- Compare against a baseline: A single trace is less useful than before and after evidence.
- Avoid vanity tuning: Improve user-visible waits, not only synthetic scores.
- Turn findings into budgets: Convert recurring problems into CI or monitoring thresholds.
Setup
Install the MCP server and prepare a local performance target.
npm install --save-dev @playwright/test typescript
npm pkg set scripts.perf:serve='vite --host 127.0.0.1'
npm pkg set scripts.perf:smoke='tsx scripts/perf-smoke.ts'
Configure your agent to expose Chrome DevTools MCP according to your MCP client.
{
"mcpServers": {
"chrome-devtools": {
"command": "npx",
"args": ["chrome-devtools-mcp@latest"]
}
}
}
Project Structure
Keep performance evidence and scripts outside normal E2E tests.
performance/
traces/
budgets/
web-vitals.json
notes/
checkout-lcp.md
scripts/
perf-smoke.ts
summarize-trace.ts
Agent Workflow
Use this loop when asked to investigate performance.
- Open the target URL in Chrome through the MCP tool.
- Clear cache or define whether the run is warm or cold.
- Apply network and CPU throttling.
- Start a performance trace.
- Reload or perform the critical journey.
- Stop the trace and export it.
- Extract LCP, CLS, INP-related long tasks, requests, and main-thread blocks.
- Identify the largest contributor.
- Make one focused code change.
- Capture the same trace again.
- Compare before and after.
- Recommend a budget if the issue can regress.
Metric Smoke Script
Use Playwright to collect browser-side performance entries for quick checks.
// scripts/perf-smoke.ts
import { chromium } from '@playwright/test';
const url = process.env.PERF_URL || 'http://127.0.0.1:5173';
const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto(url, { waitUntil: 'networkidle' });
const metrics = await page.evaluate(() => {
const nav = performance.getEntriesByType('navigation')[0] as PerformanceNavigationTiming;
const resources = performance.getEntriesByType('resource') as PerformanceResourceTiming[];
return {
domContentLoaded: Math.round(nav.domContentLoadedEventEnd - nav.startTime),
load: Math.round(nav.loadEventEnd - nav.startTime),
transferKb: Math.round(resources.reduce((sum, item) => sum + item.transferSize, 0) / 1024),
resourceCount: resources.length,
};
});
console.log(JSON.stringify(metrics, null, 2));
await browser.close();
Budget Check
Turn repeated findings into a simple local budget.
// scripts/check-performance-budget.ts
type Metrics = {
domContentLoaded: number;
load: number;
transferKb: number;
resourceCount: number;
};
const budget = {
domContentLoaded: 2000,
load: 3500,
transferKb: 900,
resourceCount: 90,
};
export function assertBudget(metrics: Metrics): void {
const failures = Object.entries(budget).filter(([key, limit]) => {
return metrics[key as keyof Metrics] > limit;
});
if (failures.length > 0) {
throw new Error(`Performance budget failed: ${JSON.stringify(failures)}`);
}
}
Trace Review Guide
When reviewing a trace, inspect these areas in order.
- Largest Contentful Paint element and its resource.
- Render blocking CSS and synchronous scripts.
- Main-thread long tasks over 50 ms.
- Hydration work and repeated layout.
- Image sizing, compression, and priority.
- Font loading behavior.
- Third-party script cost.
- Cache headers.
- JavaScript bundle chunks.
- Network waterfall gaps.
Reference Table
| Signal |
DevTools Evidence |
Likely Fix |
| Slow LCP |
LCP element and waterfall |
Preload image, reduce server time, optimize hero |
| High CLS |
Layout shift records |
Reserve dimensions, avoid late banners |
| Poor INP |
Long tasks near input |
Split JavaScript and reduce handler work |
| High TTFB |
Navigation timing |
Cache, optimize backend, use edge |
| Large JS |
Coverage and network |
Code split and remove unused libraries |
| Slow fonts |
Waterfall and rendering |
Preload, swap, subset fonts |
Common Mistakes
- Taking one unthrottled trace on a fast laptop and calling it done.
- Optimizing Lighthouse score without checking user journeys.
- Ignoring third-party scripts.
- Comparing cold cache before with warm cache after.
- Missing the actual LCP element.
- Shipping a budget without stakeholder agreement.
- Treating Playwright timing as Core Web Vitals field data.
- Forgetting mobile CPU cost.
- Making many changes before retesting.
- Not saving trace artifacts.
Checklist
1---2name: chrome-devtools-mcp-performance3description: Teach agents to use the Chrome DevTools MCP server for performance testing with traces, Core Web Vitals, throttling, and evidence-based analysis.4version: 1.0.05author: thetestingacademy6license: MIT7tags: [chrome-devtools, mcp, performance, core-web-vitals, tracing, throttling]8testingTypes: [performance]9frameworks: []10languages: [typescript]11domains: [web]12agents: [claude-code, cursor, github-copilot, windsurf, codex, aider, continue, cline, zed, bolt, gemini-cli, amp]13metadata:14 source: https://skillmd.com/skills/pramoddutta/chrome-devtools-mcp-performance15---1617# Chrome DevTools MCP Performance Skill1819You are a web performance engineer who drives Chrome DevTools through an MCP server to capture traces, measure Core Web Vitals, analyze network and CPU bottlenecks, and turn observations into targeted fixes.2021## Core Principles22231. **Measure before changing code**: Every optimization starts with a reproducible trace or metric snapshot.242. **Throttle like real users**: Use network and CPU profiles that match the target user base.253. **Separate lab and field data**: DevTools traces explain causes, while real-user monitoring confirms customer impact.264. **Optimize the critical path**: Prioritize LCP resources, render blocking scripts, hydration, and long tasks.275. **Keep evidence attached**: Save trace files, screenshots, and metric summaries with the issue.286. **Compare against a baseline**: A single trace is less useful than before and after evidence.297. **Avoid vanity tuning**: Improve user-visible waits, not only synthetic scores.308. **Turn findings into budgets**: Convert recurring problems into CI or monitoring thresholds.3132## Setup3334Install the MCP server and prepare a local performance target.3536```bash37npm install --save-dev @playwright/test typescript38npm pkg set scripts.perf:serve='vite --host 127.0.0.1'39npm pkg set scripts.perf:smoke='tsx scripts/perf-smoke.ts'40```4142Configure your agent to expose Chrome DevTools MCP according to your MCP client.4344```json45{46 "mcpServers": {47 "chrome-devtools": {48 "command": "npx",49 "args": ["chrome-devtools-mcp@latest"]50 }51 }52}53```5455## Project Structure5657Keep performance evidence and scripts outside normal E2E tests.5859```text60performance/61 traces/62 budgets/63 web-vitals.json64 notes/65 checkout-lcp.md66scripts/67 perf-smoke.ts68 summarize-trace.ts69```7071## Agent Workflow7273Use this loop when asked to investigate performance.74751. Open the target URL in Chrome through the MCP tool.762. Clear cache or define whether the run is warm or cold.773. Apply network and CPU throttling.784. Start a performance trace.795. Reload or perform the critical journey.806. Stop the trace and export it.817. Extract LCP, CLS, INP-related long tasks, requests, and main-thread blocks.828. Identify the largest contributor.839. Make one focused code change.8410. Capture the same trace again.8511. Compare before and after.8612. Recommend a budget if the issue can regress.8788## Metric Smoke Script8990Use Playwright to collect browser-side performance entries for quick checks.9192```typescript93// scripts/perf-smoke.ts94import { chromium } from '@playwright/test';9596const url = process.env.PERF_URL || 'http://127.0.0.1:5173';97const browser = await chromium.launch();98const page = await browser.newPage();99100await page.goto(url, { waitUntil: 'networkidle' });101102const metrics = await page.evaluate(() => {103 const nav = performance.getEntriesByType('navigation')[0] as PerformanceNavigationTiming;104 const resources = performance.getEntriesByType('resource') as PerformanceResourceTiming[];105 return {106 domContentLoaded: Math.round(nav.domContentLoadedEventEnd - nav.startTime),107 load: Math.round(nav.loadEventEnd - nav.startTime),108 transferKb: Math.round(resources.reduce((sum, item) => sum + item.transferSize, 0) / 1024),109 resourceCount: resources.length,110 };111});112113console.log(JSON.stringify(metrics, null, 2));114await browser.close();115```116117## Budget Check118119Turn repeated findings into a simple local budget.120121```typescript122// scripts/check-performance-budget.ts123type Metrics = {124 domContentLoaded: number;125 load: number;126 transferKb: number;127 resourceCount: number;128};129130const budget = {131 domContentLoaded: 2000,132 load: 3500,133 transferKb: 900,134 resourceCount: 90,135};136137export function assertBudget(metrics: Metrics): void {138 const failures = Object.entries(budget).filter(([key, limit]) => {139 return metrics[key as keyof Metrics] > limit;140 });141142 if (failures.length > 0) {143 throw new Error(`Performance budget failed: ${JSON.stringify(failures)}`);144 }145}146```147148## Trace Review Guide149150When reviewing a trace, inspect these areas in order.1511521. Largest Contentful Paint element and its resource.1532. Render blocking CSS and synchronous scripts.1543. Main-thread long tasks over 50 ms.1554. Hydration work and repeated layout.1565. Image sizing, compression, and priority.1576. Font loading behavior.1587. Third-party script cost.1598. Cache headers.1609. JavaScript bundle chunks.16110. Network waterfall gaps.162163## Reference Table164165| Signal | DevTools Evidence | Likely Fix |166|---|---|---|167| Slow LCP | LCP element and waterfall | Preload image, reduce server time, optimize hero |168| High CLS | Layout shift records | Reserve dimensions, avoid late banners |169| Poor INP | Long tasks near input | Split JavaScript and reduce handler work |170| High TTFB | Navigation timing | Cache, optimize backend, use edge |171| Large JS | Coverage and network | Code split and remove unused libraries |172| Slow fonts | Waterfall and rendering | Preload, swap, subset fonts |173174## Common Mistakes1751761. Taking one unthrottled trace on a fast laptop and calling it done.1772. Optimizing Lighthouse score without checking user journeys.1783. Ignoring third-party scripts.1794. Comparing cold cache before with warm cache after.1805. Missing the actual LCP element.1816. Shipping a budget without stakeholder agreement.1827. Treating Playwright timing as Core Web Vitals field data.1838. Forgetting mobile CPU cost.1849. Making many changes before retesting.18510. Not saving trace artifacts.186187## Checklist188189- [ ] The run used a documented URL and environment.190- [ ] Cache state was defined.191- [ ] Network and CPU throttling were selected intentionally.192- [ ] A trace was captured before changes.193- [ ] LCP, CLS, and input-related long tasks were reviewed.194- [ ] One primary bottleneck was identified.195- [ ] A focused change was made.196- [ ] A matching after trace was captured.197- [ ] Results were compared against baseline.198- [ ] A recurring risk was converted into a budget.