ruslanlap/pagespeed-insights-mcp

**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)
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:
Codex / OpenAI
Add to your configuration (TOML):
> **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):
**Project-scoped example** (put in this repo's .grok/config.toml for local dist/index.js + tighter Serena):
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:**
| Category | Score | Status |
|---|---|---|
| **Performance (mobile)** | **54/100** | 🔴 Poor |
| **Performance (desktop)** | **52/100** | 🔴 Poor |
**Core metrics (mobile):**
| Metric | Value | Rating |
|---|---|---|
| First Contentful Paint | 11.9 s | 🔴 Poor |
| Largest Contentful Paint | 13.4 s | 🔴 Poor |
| Total Blocking Time | 30 ms | 🟢 Excellent |
| Cumulative Layout Shift | 0.07 | 🟢 Good |
| Speed Index | 11.9 s | 🔴 Poor |
**CrUX field data — real users, github.com origin (phone):**
| Metric | p75 (real users) |
|---|---|
| First Contentful Paint | 1.9 s |
| Largest Contentful Paint | 2.2 s |
| Interaction to Next Paint | 243 ms |
| Cumulative Layout Shift | 0.02 |
> 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.