pagespeed-insights-mcp

# PageSpeed Insights MCP Server

[![MCP Toplist](https://mcptoplist.com/badge/glama%2Fruslanlap%2Fpagespeed-insights-mcp.svg)](https://mcptoplist.com/server/glama%2Fruslanlap%2Fpagespeed-insights-mcp)

<p align="center">
  <img src="https://raw.githubusercontent.com/ruslanlap/pagespeed-insights-mcp/master/assets/1.png" alt="PageSpeed MCP chat demo" width="48%" />
  <img src="https://raw.githubusercontent.com/ruslanlap/pagespeed-insights-mcp/master/assets/2.png" alt="PageSpeed MCP terminal demo" width="48%" />
</p>

[![npm version](https://img.shields.io/npm/v/pagespeed-insights-mcp.svg)](https://www.npmjs.com/package/pagespeed-insights-mcp)
[![npm downloads](https://img.shields.io/npm/dm/pagespeed-insights-mcp.svg)](https://www.npmjs.com/package/pagespeed-insights-mcp)
[![GitHub Package Version](https://img.shields.io/github/package-json/v/ruslanlap/pagespeed-insights-mcp?label=github%20package)](https://github.com/ruslanlap/pagespeed-insights-mcp/pkgs/npm/pagespeed-insights-mcp)
[![CI](https://github.com/ruslanlap/pagespeed-insights-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/ruslanlap/pagespeed-insights-mcp/actions/workflows/ci.yml)
[![Documentation](https://img.shields.io/badge/docs-online-blue.svg)](https://ruslanlap.github.io/pagespeed-insights-mcp/)
[![Live Demo](https://img.shields.io/badge/demo-live-blueviolet.svg)](https://ruslanlap.github.io/pagespeed-insights-mcp/demo/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**18-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.

> **🎬 [View Interactive Demo →](https://ruslanlap.github.io/pagespeed-insights-mcp/demo/)** — See all 18 tools in action with animated examples
> Fallback URL: [https://ruslanlap.github.io/pagespeed-insights-mcp/demo.html](https://ruslanlap.github.io/pagespeed-insights-mcp/demo.html)

## 📖 Table of Contents

- [⚡ Quick Start (Copy & Paste)](#-quick-start-copy--paste)
  - [Claude Desktop](#claude-desktop)
  - [Codex / OpenAI](#codex--openai)
- [📚 Documentation](#-documentation)
- [📝 Release Notes](#-release-notes)
- [🎯 Why You Need This](#-why-you-need-this)
- [✨ Features](#-features)
  - [Core Features](#core-features)
  - [Advanced Analysis Tools (New!)](#advanced-analysis-tools-new)
- [🚀 Quick Installation](#-quick-installation)
  - [Option 1: Automatic Installation (Recommended)](#option-1-automatic-installation-recommended)
  - [Option 2: Via npm or GitHub Packages](#option-2-via-npm-or-github-packages)
    - [From npm (Public Registry)](#from-npm-public-registry)
    - [From GitHub Packages](#from-github-packages)
  - [🔧 Configuration](#-configuration)
  - [📝 MCP Configuration Examples](#-mcp-configuration-examples)
    - [For Claude Desktop](#for-claude-desktop-with-pino-pretty-logging)
    - [For Codex](#for-codex-with-pino-pretty-logging)
  - [Claude Desktop Configuration](#claude-desktop-configuration)
  - [Google Antigravity](#google-antigravity)
  - [Option 3: Docker](#option-3-docker)
- [🔑 Getting Google API Key](#-getting-google-api-key)
- [⚙️ Claude Desktop Configuration](#-claude-desktop-configuration)
  - [Automatic Configuration](#automatic-configuration)
  - [Manual Configuration](#manual-configuration)
    - [For npm / Global Installation](#for-npm-installation-and-global-installation)
    - [For GitHub Packages](#for-github-packages-installation)
    - [For Docker](#for-docker)
- [💻 Usage](#-usage)
  - [🔍 Full Page Analysis](#-full-page-analysis)
  - [📱 Mobile Device Analysis](#-mobile-device-analysis)
  - [⚡ Quick Performance Overview](#-quick-performance-overview)
  - [🖥️ Desktop Analysis](#-desktop-analysis)
  - [🌐 Multi-Category Analysis](#-multi-category-analysis)
  - [🎯 Smart Performance Recommendations](#-smart-performance-recommendations)
  - [💾 Cache Management](#-cache-management)
  - [📸 Visual Analysis](#-visual-analysis)
  - [🎯 Element-Level Debugging](#-element-level-debugging)
  - [🌐 Network Waterfall Analysis](#-network-waterfall-analysis)
  - [⚡ JavaScript Performance](#-javascript-performance)
  - [🖼️ Image Optimization Opportunities](#-image-optimization-opportunities)
  - [🚫 Render-Blocking Resources](#-render-blocking-resources)
  - [🔌 Third-Party Script Impact](#-third-party-script-impact)
  - [📊 Full Lighthouse Audit](#-full-lighthouse-audit)
- [🛠️ Available Tools](#available-tools)
  - [Core Analysis](#core-analysis)
  - [CrUX & Comparison](#crux--comparison)
  - [Advanced Diagnostics](#advanced-diagnostics)
- [📊 Complete Ratings for example.com](#complete-ratings-for-examplecom)
- [💻 Development](#development)
- [🔧 Troubleshooting](#troubleshooting)
- [📋 Requirements](#requirements)
- [🔒 Security](#security)
- [🙏 Acknowledgments](#acknowledgments)
- [📄 License](#license)
- [💬 Support](#support)

---

## ⚡ Quick Start (Copy & Paste)

### Claude Desktop

Add to your `claude_desktop_config.json`:

```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):

```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):

```toml
[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):

```toml
[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__analyze_page`, `pagespeed-insights__get_crux_data` etc. (namespaced)

## 📚 Documentation

We have comprehensive documentation available online.

[**👉 View Full Documentation Site**](https://ruslanlap.github.io/pagespeed-insights-mcp/)

- [🚀 **Getting Started**](https://ruslanlap.github.io/pagespeed-insights-mcp/getting-started/)
- [🛠️ **Tools Reference**](https://ruslanlap.github.io/pagespeed-insights-mcp/features/tools/)
- [🏗️ **Architecture**](https://ruslanlap.github.io/pagespeed-insights-mcp/developers/architecture/)

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

## 📝 Release Notes

Current release: **v1.5.1**.

> 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`](./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 18 specialized tools 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

- 🚀 **Performance Analysis** of web pages using Google PageSpeed Insights
- 📱 **Multi-platform Support**: mobile and desktop devices
- 🔍 **Detailed Lighthouse Reports** with comprehensive metrics
- 📊 **Simplified Reports** with key performance indicators
- 🎯 **Smart Recommendations** with priority scoring and actionable fixes
- 💾 **Intelligent Caching** to reduce API calls and improve performance
- 🌍 **Localization** - support for multiple languages
- ⚡ **Quick Installation** - one command setup
- 🐳 **Docker Support** for containerized deployment

### Advanced Analysis Tools (New!)

- 📸 **Visual Analysis** - Screenshots, filmstrip, and full-page captures
- 🎯 **Element-Level Debugging** - Find specific DOM elements causing issues
- 🌐 **Network Waterfall** - Detailed request timing and resource loading
- ⚡ **JavaScript Profiling** - Execution breakdown and unused code detection
- 🖼️ **Image Optimization** - Specific image issues with exact savings
- 🚫 **Render-Blocking Analysis** - Critical request chains and dependencies
- 🔌 **Third-Party Impact** - Script impact grouped by provider
- 📊 **Full Audits** -