MCP server for Google PageSpeed Insights API that enables web page performance analysis directly through Claude.

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.

• 🚀 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

• 📸 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

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

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

# Global installation from npm
npm install -g pagespeed-insights-mcp
# Or use without installation
npx pagespeed-insights-mcp
# Specific version
npm install -g pagespeed-insights-mcp@1.0.6

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

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 GITHUB_PACKAGES.md or visit the GitHub Packages page

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

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

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

Example configuration files are available in the examples directory.

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

1. Go to Google Cloud Console
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 enable it
4. Create an API key:
   • Go to "APIs & Services" → "Credentials"
   • Click "Create Credentials" → "API Key"
   • Copy the generated key

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

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

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

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

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

After configuration, simply ask Claude any of these commands:

Analyze the performance of https://example.com

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

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

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

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

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

Clear the cache to get fresh data for all subsequent requests

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

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

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

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

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

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

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

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

Complete page analysis with all Lighthouse metrics.

Parameters:

• url (required): URL of the page to analyze
• strategy: "mobile" or "desktop" (default: "mobile")
• category: array of categories ["performance", "accessibility", "best-practices", "seo", "pwa"]
• locale: locale for results (default: "en")

Simplified report with key performance metrics.

Generate smart performance recommendations with priority scoring and actionable fixes.

Parameters:

• url (required): URL of the page to analyze
• strategy: "mobile" or "desktop" (default: "mobile")
• category: array of categories to analyze (default: ["performance", "accessibility", "best-practices", "seo"])
• locale: locale for results (default: "en")

Clear the internal cache to force fresh API requests for all subsequent analyses.

Get screenshots and visual timeline showing how the page loads.

Parameters:

• url (required): URL of the page to analyze
• strategy: "mobile" or "desktop" (default: "mobile")

Returns:

• Final screenshot of the loaded page
• Filmstrip showing page load progression
• Full-page screenshot with DOM node mapping

Get specific DOM elements causing performance issues.

Parameters:

• url (required): URL of the page to analyze
• strategy: "mobile" or "desktop" (default: "mobile")

Returns:

• LCP (Largest Contentful Paint) element details
• CLS (Cumulative Layout Shift) causing elements
• Lazy-loaded LCP warnings

Get detailed network waterfall showing all requests with timing and size.

Parameters:

• url (required): URL of the page to analyze
• strategy: "mobile" or "desktop" (default: "mobile")

Returns:

• All network requests with timing data
• Resource breakdown by type
• Total transfer size and request count
• Network RTT and server latency

Get JavaScript execution breakdown showing performance impact.

Parameters:

• url (required): URL of the page to analyze
• strategy: "mobile" or "desktop" (default: "mobile")

Returns:

• JavaScript bootup time by script
• Main thread work breakdown
• Unused JavaScript analysis
• Duplicated JavaScript modules

Get specific images needing optimization with exact savings potential.

Parameters:

• url (required): URL of the page to analyze
• strategy: "mobile" or "desktop" (default: "mobile")

Returns:

• Improperly sized images
• Offscreen images (lazy-loading candidates)
• Unoptimized images
• Modern format recommendations (WebP/AVIF)

Get render-blocking resources and critical request chains.

Parameters:

• url (required): URL of the page to analyze
• strategy: "mobile" or "desktop" (default: "mobile")

Returns:

• Render-blocking CSS and JavaScript files
• Critical request chains showing dependencies
• Total blocking time

Get third-party script impact analysis grouped by entity.

Parameters:

• url (required): URL of the page to analyze
• strategy: "mobile" or "desktop" (default: "mobile")

Returns:

• Impact by provider (Google, Facebook, etc.)
• Transfer size and blocking time per provider
• Recommended facade replacements

Get comprehensive audit results for all Lighthouse categories.

Parameters:

• url (required): URL of the page to analyze
• strategy: "mobile" or "desktop" (default: "mobile")
• categories: array of categories to audit (default: ["performance", "accessibility", "best-practices", "seo"])

Returns:

• Scores for all categories
• Detailed Core Web Vitals and metrics
• Key failing audits for each category
• Framework-specific advice (if applicable)

answer example from Claude Desktop with pagespeed-insights-mcp 🔥🔥🔥

Now I have the full analysis! Here are all the ratings:

1. 🔴 High Priority:
   • Optimize image sizes (save 1+ MB)
   • Fix aria-label mismatches for accessibility
2. 🟡 Medium Priority:
   • Improve caching policy (TTL >600s)
   • Add width/height attributes for images
3. 🟢 Low Priority:
   • Optimize forced reflows in JavaScript

Overall Rating: Good with potential for improvement

• SEO: Perfect (100/100) 🏆
• Best Practices: Excellent (96/100) 🏆
• Accessibility: Good (92/100) ✅
• Performance: Needs attention (67/100) ⚠️

The site has excellent SEO optimization and follows best practices, but needs image optimization to improve performance.

Parameters:

• url (required): URL of the page to analyze
• strategy: "mobile" or "desktop" (default: "mobile")

For better log formatting during development, it is recommended to install pino-pretty globally:

npm install -g pino-pretty

# Development mode
npm run dev
# Build project
npm run build
# Run built server
npm start

Ensure the GOOGLE_API_KEY environment variable is set in your Claude Desktop configuration.

Check if PageSpeed Insights API is enabled in your Google Cloud project.

Ensure the URL includes the protocol (https:// or https://).

Special thanks to @engmsaleh (Mohamed Saleh Zaied) for his significant contribution to the development of this project.

MIT

For bug reports or feature requests, please create an issue in the repository.