Pagespeed Insights Mcp

PageSpeed Insights MCP Server

[](https://www.npmjs.com/package/pagespeed-insights-mcp) [](https://www.npmjs.com/package/pagespeed-insights-mcp) [](https://github.com/ruslanlap/pagespeed-insights-mcp/pkgs/npm/pagespeed-insights-mcp) [](https://github.com/ruslanlap/pagespeed-insights-mcp/actions/workflows/ci.yml) [](https://ruslanlap.github.io/pagespeed-insights-mcp/) [](https://ruslanlap.github.io/pagespeed-insights-mcp/demo/) [](https://opensource.org/licenses/MIT) [](https://agent-tool-intel-production.up.railway.app)

16-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 → — See all 16 tools in action with animated examples > Fallback URL: 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)
• [✨ 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:

{
  "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__analyze_page, pagespeed-insights__get_crux_data etc. (namespaced)

📚 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: v1.2.3.

v1.2.3 — Google Antigravity support

• Added a Google Antigravity MCP configuration guide for ~/.gemini/config/mcp_config.json.
• Added an Antigravity-ready example configuration in [examples/antigravity-config.json](./examples/antigravity-config.json).
• Tightened release automation so important MCP client integration documentation can trigger a patch release when commits use scoped conventional commit messages such as docs(antigravity): ..., docs(integration): ..., or docs(config): ....

For the complete release history, see [CHANGELOG.md](./CHANGELOG.md).

✨ 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 - Complete Lighthouse audits for all categories

🚀 Quick Installation

Option 1: Automatic Installation (Recommended)

# Set environment variable
export GOOGLE_API_KEY=your-google-api-key

curl -sSL https://raw.githubusercontent.com/ruslanlap/pagespeed-insights-mcp/master/scripts/install.sh | bash

The installer uses the public npm package (pagespeed-insights-mcp) by default. To install the scoped GitHub Packages build instead, configure GitHub Packages authentication first and run:

curl -sSL https://raw.githubusercontent.com/ruslanlap/pagespeed-insights-mcp/master/scripts/install.sh | \
  PAGESPEED_INSIGHTS_MCP_PACKAGE=@ruslanlap/pagespeed-insights-mcp bash

Option 2: Via npm or GitHub Packages

From npm (Public Registry)

# Global installation from npm
npm install -g pagespeed-insights-mcp

# Or use without installation
npx pagespeed-insights-mcp

From GitHub Packages

# First configure authentication (see GITHUB_PACKAGES.md for details)
# Then install globally
npm install -g @ruslanlap/pagespeed-insights-mcp

> Note: This package is available on both npm and GitHub Packages. > > - For npm: Use npm install pagespeed-insights-mcp > - For GitHub Packages: Use npm install @ruslanlap/pagespeed-insights-mcp (requires GitHub authentication) > > For detailed instructions on installing from GitHub Packages, see [GITHUBPACKAGES.md](GITHUBPACKAGES.md) or visit the GitHub Packages page

🔧 Configuration

The MCP server requires a Google API key to access the PageSpeed Insights API.

# Set environment variable
export GOOGLE_API_KEY=your-google-api-key

# Windows
$env:GOOGLE_API_KEY="your-google-api-key"

# Or pass directly when running
GOOGLE_API_KEY=your-google-api-key npx pagespeed-insights-mcp

📝 MCP Configuration Examples

For Claude Desktop (with pino-pretty logging):

"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"
  }
}

For Codex (with pino-pretty logging):

[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: These examples include pino-pretty for better log formatting. For production use without pretty logs, see the [Logging section](#logging--pino-pretty-in-mcp-environments) below.

Claude Desktop Configuration

To use this MCP server with Claude Desktop, add the following to your Claude Desktop configuration file:

{
  "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"
      }
    }
  }
}

Google Antigravity

To use this MCP server with Google Antigravity, add the following configuration to your global settings file (~/.gemini/config/mcp_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"
      }
    }
  }
}

Example configuration files are available in the [examples](./examples/) directory.

Option 3: Docker

docker build -t pagespeed-insights-mcp .
docker run -e GOOGLE_API_KEY=your-key pagespeed-insights-mcp

🔑 Getting Google API Key

To use this MCP server, you need a Google API key with the PageSpeed Insights API enabled.

> [!TIP] > ⚡ Quick Setup Link: You can go directly to the Google Cloud Credentials Setup Page to quickly create a key in your project.

Step-by-Step Guide

1. Go to the Google Cloud Console (or use the Quick Setup Link).
2. Create a new project or select an existing one.
3. Enable PageSpeed Insights API:

• Navigate to APIs & Services → Library.
• Search for "PageSpeed Insights API" and click Enable.

1. Create an API key:

• Go to APIs & Services → Credentials.
• Click Create Credentials → API Key.
• Copy the generated key and set it as GOOGLE_API_KEY in your configuration.

⚙️ Claude Desktop Configuration

Automatic Configuration

If you used the scripts/install.sh script, the configuration was created automatically.

Manual Configuration

Add the configuration to your Claude Desktop file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/claude/claude_desktop_config.json

For npm installation and global installation

{
  "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"
      }
    }
  }
}

For GitHub Packages installation

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

For Docker:

{
  "mcpServers": {
    "pagespeed-insights": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env",
        "GOOGLE_API_KEY=your-google-api-key-here",
        "pagespeed-insights-mcp"
      ]
    }
  }
}

Restart Claude Desktop after configuration!

💻 Usage

After configuration, simply ask Claude any of these commands:

🔍 Full page analysis

Analyze the performance of https://example.com

📱 Mobile device analysis

Analyze https://example.com for mobile devices with all categories

⚡ Quick performance overview

Get a quick performance report for https://example.com

🖥️ Desktop analysis

Analyze https://example.com performance for desktop devices

🌐 Multi-category analysis

Perform a full audit of https://example.com including SEO, accessibility, and best practices

🎯 Smart performance recommendations

Get smart recommendations for improving https://example.com performance

💾 Cache management

Clear the cache to get fresh data for all subsequent requests

📸 Visual analysis

Get visual analysis for https://example.com showing screenshots and loading timeline

🎯 Element-level debugging

Show me which specific elements are causing performance issues on https://example.com

🌐 Network waterfall analysis

Analyze the network requests and resource loading for https://example.com

⚡ JavaScript performance

Get JavaScript execution breakdown for https://example.com

🖼️ Image optimization opportunities

Show me which images need optimization on https://example.com

🚫 Render-blocking resources

Find render-blocking resources on https://example.com

🔌 Third-party script impact

Analyze third-party script impact on https://example.com performance

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ruslanlap
• Source: ruslanlap/pagespeed-insights-mcp
• License: MIT
• Homepage: https://ruslanlap.github.io/ruslanlap_buymeacoffe/

Install and usage instructions live in the source repository linked above.