Pagespeed Insights MCP

PageSpeed Insights MCP Server

Six-tool MCP server for Google PageSpeed Insights & Chrome UX Report APIs. Analyze, compare, and optimize web performance directly through Claude, Cursor, or any MCP-compatible AI client.

⚡ Quick Start (Copy & Paste)

{

"mcpServers": { "pagespeed-insights": { "command": "npx", "args": ["-y", "pagespeed-insights-mcp"], "env": { "GOOGLE_API_KEY": "your-google-api-key" } } } }

Get a free API key at Google Cloud Console → paste into Claude Desktop's claude_desktop_config.json → restart. Done. (Codex/OpenAI config, Docker)

🔥 What Makes It Different

Most PageSpeed MCP servers wrap one tool: "run PSI on a URL." This server ships six workflow tools covering the full performance workflow — not just a score, but an action plan:

• Full toolkit: page analysis, CrUX real-user data (URL + origin), Lighthouse audits, multi-page & batch comparison, baselines, and regression tracking
• Deep diagnostics: element-level, network, JavaScript, image optimization, render-blocking, and third-party impact analysis
• Actionable output: a recommendations engine that turns raw Lighthouse data into prioritized fixes, plus visual analysis of screenshots
• Practical extras: caching for repeat runs and smart recommendations tuned for AI agents to act on
• Battle-tested: published on npm, listed in the Official MCP Registry and Glama, CI-tested with Vitest

🎬 [View Interactive Demo →](https://ruslanlap.github.io/pagespeed-insights-mcp/demo/) — See the tools in action with animated examples

Fallback URL: https://ruslanlap.github.io/pagespeed-insights-mcp/demo.html

📖 Table of Contents

• ⚡ Quick Start (Copy & Paste)
• 🔥 What Makes It Different
• ⚙️ Client Configuration
• 📊 Example Output
• 📚 Documentation
• 📝 Release Notes
• 🎯 Why You Need This
• ✨ Features
• 🚀 Quick Installation
• 🔑 Getting Google API Key
• ⚙️ Claude Desktop Configuration
• 💻 Usage
• Available Tools
• MCP Prompts (Slash Commands)
• MCP Resources
• ✨ Rich Visual & Aesthetic Outputs
• Development
• Troubleshooting
• Requirements
• Security
• Acknowledgments
• License
• Support

⚙️ Client Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{

"mcpServers": { "pagespeed-insights": { "command": "npx", "args": ["-y", "-p", "pino-pretty", "-p", "pagespeed-insights-mcp", "pagespeed-insights-mcp"], "env": { "GOOGLE_API_KEY": "your-google-api-key-here" } } } }

Codex / OpenAI

Add to your configuration (TOML):

[mcp_servers.pagespeed-insights]

command = "npx" args = [ "-y", "-p", "pino-pretty", "-p", "pagespeed-insights-mcp", "pagespeed-insights-mcp" ] env = { GOOGLE_API_KEY = "your-google-api-key-here" }

Note: The pino-pretty package is required for proper log formatting. The above configurations ensure it is installed automatically via npx.

For Grok Build (config.toml)

Add to ~/.grok/config.toml (global) or /.grok/config.toml (project-scoped, higher priority):

[mcp_servers.pagespeed-insights]

command = "npx" args = ["-y", "-p", "pino-pretty", "-p", "pagespeed-insights-mcp", "pagespeed-insights-mcp"] env = { GOOGLE_API_KEY = "${GOOGLE_API_KEY}" } enabled = true

Recommended companion professional MCPs (add once):

[mcp_servers.github] — PRs, issues, code search

[mcp_servers.context7] — fresh library docs (Upstash)

[mcp_servers.serena] — semantic code intelligence (uses your .serena/ if present)

Project-scoped example (put in this repo's .grok/config.toml for local dist/index.js + tighter Serena):

[mcp_servers.pagespeed-insights]

command = "node" args = ["/home/ubuntuvm/Projects/pagespeed-insights-mcp/dist/index.js"] env = { GOOGLE_API_KEY = "${GOOGLE_API_KEY}", NODE_ENV = "development" }

Verification inside Grok session:

• /mcps (or Ctrl+L → MCP tab) → ensure pagespeed-insights shows "running"
• Use tools: pagespeed-insights__pagespeed_analyze_page, pagespeed-insights__pagespeed_get_field_data, etc. (namespaced)

📊 Example Output

Real pagespeed_analyze_page results for github.com — one mobile Lighthouse run. CrUX numbers come from pagespeed_get_field_data with scope: "origin":

Lighthouse lab scores:

Core metrics (mobile):

CrUX field data — real users, github.com origin (phone):

Results vary between runs — Lighthouse lab data is noisy (a single run is one sample). Use runs: 3-5 for medians.

Lab vs field: Lighthouse throttles the connection (hence 54/100 mobile), while CrUX shows how actual GitHub visitors experience it — both views come straight from this server's tools.

📚 Documentation

We have comprehensive documentation available online.

👉 View Full Documentation Site

• 🚀 Getting Started
• 🛠️ Tools Reference
• 🏗️ Architecture

You can also view the raw markdown files in the docs/ directory or run mkdocs serve locally.

📝 Release Notes

Current release: see the version badges at the top of this README.

Latest Highlights:

• ✨ Rich Aesthetic & Visual Formatters:
• Unicode Score Bars: Gauge progress visualization (█████████████░░░ 85/100 🟢 Good) for instant visual feedback.
• Core Web Vitals Scorecards: Clean markdown tables classified with official Google 2026 guidelines (🟢 Good, 🟡 Needs Improvement, 🔴 Poor).
• GitHub Shield Badges: Direct copy-paste markdown badges for repository READMEs with direct web.dev analysis links.
• Modernized Mermaid Architecture Maps: High-contrast, dark-mode friendly flowcharts with color-coded nodes.
• Recommendation Callouts: Visual priority summary callout cards (🔴 High | 🟡 Medium | 🟢 Low | Impact: High).

• 💬 Native MCP Prompts (Slash Commands):
• Interactive prompts exposed to Claude Desktop, Cursor, and Cline slash menus:
• /performance-audit: Guided 4-step performance triage with prioritized remediation.
• /release-comparison: Staging vs production delta verification with a clear GO / NO-GO decision.
• /core-web-vitals-deepdive: Deep-dive contrasting real-user CrUX field data with synthetic Lighthouse lab simulations.

• 📚 Native MCP Resources:
• Direct context URIs without tool executions:
• pagespeed://web-vitals-guide: 2026 Core Web Vitals thresholds and optimization playbooks.
• pagespeed://baselines: Locally recorded performance baselines for regression tracking.

• 🧪 Enterprise-Grade Test Suite & Resilience:
• Expanded test coverage across 21 test suites and 304 tests (100% passing).
• High coverage standards: 96.43% statements, 85.82% branch coverage (100% on formatters, resources, and baselines).
• Clean, single-run execution across CI and prepublishOnly (lint, typecheck, test, build).

• v2 Core Architecture:
• Six workflow-oriented pagespeed_* tools replace the former 19 v1 endpoint-shaped tools; all data tools support Markdown or JSON with structured results.

The badges at the top of this README update automatically on every release (npm version, GitHub package version, downloads). No manual edits needed.

For the complete release history, see CHANGELOG.md.

🎯 Why You Need This

Pain point 1 — "My page is slow but I don't know why." You open PageSpeed Insights, get a wall of data, and still can't tell what to fix first. This MCP gives your AI assistant six focused workflows that cut through the noise: it identifies the exact render-blocking resources, the specific images wasting 2 MB, the third-party scripts eating 1.5 s of main-thread time — and ranks them by impact. Ask "why is my site slow?" and get a prioritized fix list, not a 40-metric dashboard.

Pain point 2 — "I ship performance regressions to production." Your team moves fast, deploys daily, and nobody runs a full Lighthouse audit before each merge. By the time someone notices the Core Web Vitals dropped, the regression is already live. This MCP lets any developer paste a URL into Claude/Cursor and get a complete audit — lab data, field data from real Chrome users (CrUX), element-level CLS/LCP debugging — in seconds. It's the difference between catching a regression at your desk and di