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 → — 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
• 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 <repo>/.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: v2.0.0.

Recent highlights:

• v2.0.0 — six workflow-oriented pagespeed_* tools replace the 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 discovering it in a Slack message from the SEO team three days later.

✨ Features

Core Features