Core Web Vitals MCP Server (core-web-vitals-mcp)

FastMCP server exposing Google Chrome User Experience Report (CrUX) and PageSpeed Insights APIs for real-user Core Web Vitals (LCP, INP, CLS), 28-day field history trends, and Lighthouse lab performance audits.

The definitive Core Web Vitals diagnostics engine for AI coding agents (Claude, Cursor, Copilot, Antigravity).

1. Quickstart

Run directly without installing via uvx (Python) or npx (Node):

Via Python (uvx)

uvx core-web-vitals-mcp

Via Node (npx)

npx -y core-web-vitals-tools-mcp

2. MCP Client Configuration

Add to your MCP client config (claude_desktop_config.json, cursor.json, or Antigravity):

{
  "mcpServers": {
    "core-web-vitals": {
      "command": "uvx",
      "args": ["core-web-vitals-mcp"],
      "env": {
        "GOOGLE_API_KEY": "your_google_api_key_here"
      }
    }
  }
}

Or using npx:

{
  "mcpServers": {
    "core-web-vitals": {
      "command": "npx",
      "args": ["-y", "core-web-vitals-tools-mcp"],
      "env": {
        "GOOGLE_API_KEY": "your_google_api_key_here"
      }
    }
  }
}

3. Google API Authentication

While PageSpeed Insights can execute lab audits under limited public quota, Chrome UX Report (CrUX) queries require an authorized Google API Key:

1. Open the Google Cloud Console.
2. Select your project or create a new one.
3. Navigate to APIs & Services -> Library and enable:
   • Chrome UX Report API
   • PageSpeed Insights API
4. Navigate to APIs & Services -> Credentials -> Create Credentials -> API key.
5. Set the environment variable:

   export GOOGLE_API_KEY="AIzaSy..."
   # or
   export CRUX_API_KEY="AIzaSy..."
   

4. Tools

5. Playbook Skills

The server dynamically dissociates actionable engineering playbooks from the core runtime:

• lcp-optimization: 4-phase breakdown (TTFB, Load Delay, Load Duration, Render Delay), image format conversion, preloading, and render blocking mitigation.
• inp-debugging: Interactive latency breakdown (Input Delay, Processing, Presentation Delay), task chunking with scheduler.yield(), and long task mitigation.
• cls-remediation: Aspect-ratio reservation, fallback font metric overrides (size-adjust), and layout stability patterns.

6. Telemetry & Privacy

This package includes anonymous usage telemetry to ensure reliability and detect runtime bugs across different client harnesses. Telemetry adheres strictly to Schema v2:

• Opt-Out: Strictly respects DO_NOT_TRACK=1, DISABLE_TELEMETRY=1, MCP_TELEMETRY_OPT_OUT=1, or CORE_WEB_VITALS_TELEMETRY=false.
• Zero PII: No user URLs, personal identifiers, or authentication keys are ever captured.