PageSpeed Insights MCP Server

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

🎬 View Interactive Demo → — See all 16 tools in action with animated examples Fallback URL: https://ruslanlap.github.io/pagespeed-insights-mcp/demo.html

⚡ 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.

📚 Documentation

We have comprehensive documentation available online.

👉 View Full Documentation Site

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

✨ 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/install.sh | 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

# Specific version
npm install -g pagespeed-insights-mcp@1.0.6

From GitHub Packages

# 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

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

Example configuration files are available in the 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

Go to Google Cloud Console
Create a new project or select an existing one
Enable PageSpeed Insights API:
- Navigate to "APIs & Services" → "Library"
- Search for "PageSpeed Insights API" and enable it
Create an API key:
- Go to "APIs & Services" → "Credentials"
- Click "Create Credentials" → "API Key"
- Copy the generated key

⚙️ Claude Desktop Configuration

Automatic Configuration

If you used the 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

📊 Full Lighthouse audit

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

Available Tools

`analyze_page_speed`

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

`get_performance_summary`

Simplified report with key performance metrics.

`get_recommendations`

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_cache`

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

`get_visual_analysis`

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_element_analysis`

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_network_analysis`

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_analysis`

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_image_optimization_details`

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_details`

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_impact`

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_full_audit`

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)

Example

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

Complete Ratings for example.com

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

📊 Main Lighthouse Scores

Category	Score	Status
Performance	67/100	🟡 Needs Improvement
Accessibility	92/100	🟢 Good
Best Practices	96/100	🟢 Excellent
SEO	100/100	🟢 Perfect

⚡ Detailed Performance Metrics

Metric	Value	Score
First Contentful Paint	1.2s	🟢 Excellent (98/100)
Largest Contentful Paint	2.4s	🟡 Needs Improvement (75/100)
Speed Index	4.8s	🟡 Needs Improvement (67/100)
Total Blocking Time	60ms	🟢 Good (94/100)
Cumulative Layout Shift	0	🟢 Perfect (100/100)

♿ Detailed Accessibility Scores (92/100)

Audit	Score	Description
Label Content Name Mismatch	🔴 0/1	2 errors with aria-label
Unsized Images	🟡 0.5/1	1 image without dimensions
Color Contrast	🟢 1/1	Sufficient contrast
Button Names	🟢 1/1	Accessible button names
Link Names	🟢 1/1	Accessible link names
ARIA Roles	🟢 1/1	Correct ARIA roles
HTML Lang	🟢 1/1	Valid lang attribute
Meta Viewport	🟢 1/1	Proper viewport
Image Alt Text	🟢 1/1	Correct alt attributes
List Items	🟢 1/1	Proper list structure

🏆 Detailed Best Practices Scores (96/100)

Audit	Score	Status
Uses HTTPS	🟢 ✓	HTTPS is used
HTTP Status Code	🟢 1/1	Correct 200 status
No Console Errors	🟢 1/1	No console errors
Valid Source Maps	🟢 1/1	Valid source maps
No Notification Requests	🟢 1/1	No notification requests
Charset Declaration	🟢 1/1	Correct encoding
No Inspector Issues	🟢 1/1	No DevTools issues

🔍 Detailed SEO Scores (100/100)

Audit	Score	Status
Meta Viewport	🟢 1/1	Mobile optimized
Document Title	🟢 1/1	Title present
Meta Description	🟢 1/1	Description present
HTTP Status Code	🟢 1/1	Successful status
Link Text	🟢 1/1	Descriptive link texts
Crawlability	🟢 1/1	Available for indexing
HTML Lang	🟢 1/1	Valid document language
Hreflang	🟢 1/1	Correct hreflang attributes

🔧 Main Performance Issues

Issue	Affects	Potential Savings
Improperly sized images	LCP, FCP	1,069 KB, 170ms
Inefficient caching	Overall speed	1,445 KB
Forced Reflows	Smoothness	46.8ms
JavaScript execution time	TBT	338ms

📈 Network Metrics

Metric	Value
Server Response Time	120ms (🟢 Good)
Network RTT	Minimal
Main Thread Work	0.9s
DOM Size	453 elements (optimal)

💡 Priority Recommendations

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

🎯 Summary

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

Development

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

Logging / `pino-pretty` in MCP environments

This MCP server uses pino for logging and enables the pino-pretty transport when NODE_ENV=development.

If you just want it to work with minimal setup (Claude, Codex, etc.), set:

NODE_ENV=production GOOGLE_API_KEY=your-google-api-key npx pagespeed-insights-mcp

or in your MCP config:

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

If you want pretty logs in development via npx, you can have npx install pino-pretty alongside the server:

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

Troubleshooting

"Google API key not provided"

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

"PageSpeed Insights API error: 403"

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

"Invalid URL"

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

Acknowledgments

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

License

MIT

Support

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

Name		Name	Last commit message	Last commit date
Latest commit History 55 Commits
.github/workflows		.github/workflows
demo		demo
docs		docs
examples		examples
src		src
.dockerignore		.dockerignore
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.npmrc		.npmrc
.prettierrc		.prettierrc
.releaserc.json		.releaserc.json
1.png		1.png
2.png		2.png
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
GITHUB_PACKAGES.md		GITHUB_PACKAGES.md
LICENSE		LICENSE
PUBLISHING.md		PUBLISHING.md
README.md		README.md
TESTING.md		TESTING.md
claude-desktop-config.json		claude-desktop-config.json
docker-compose.yml		docker-compose.yml
docsbuild.sh		docsbuild.sh
install.sh		install.sh
manual-test.sh		manual-test.sh
mkdocs.yml		mkdocs.yml
package-lock.json		package-lock.json
package.json		package.json
publish.sh		publish.sh
test-mcp.js		test-mcp.js
test-tools.js		test-tools.js
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

PageSpeed Insights MCP Server

⚡ Quick Start (Copy & Paste)

Claude Desktop

Codex / OpenAI

📚 Documentation

✨ Features

Core Features

Advanced Analysis Tools (New!)

🚀 Quick Installation

Option 1: Automatic Installation (Recommended)

Option 2: Via npm or GitHub Packages

From npm (Public Registry)

From GitHub Packages

🔧 Configuration

📝 MCP Configuration Examples

For Claude Desktop (with pino-pretty logging):

For Codex (with pino-pretty logging):

Claude Desktop Configuration

Option 3: Docker

🔑 Getting Google API Key

⚙️ Claude Desktop Configuration

Automatic Configuration

Manual Configuration

For npm installation and global installation

For GitHub Packages installation

For Docker:

💻 Usage

🔍 Full page analysis

📱 Mobile device analysis

⚡ Quick performance overview

🖥️ Desktop analysis

🌐 Multi-category analysis

🎯 Smart performance recommendations

💾 Cache management

📸 Visual analysis

🎯 Element-level debugging

🌐 Network waterfall analysis

⚡ JavaScript performance

🖼️ Image optimization opportunities

🚫 Render-blocking resources

🔌 Third-party script impact

📊 Full Lighthouse audit

Available Tools

analyze_page_speed

get_performance_summary

get_recommendations

clear_cache

get_visual_analysis

get_element_analysis

get_network_analysis

get_javascript_analysis

get_image_optimization_details

get_render_blocking_details

get_third_party_impact

get_full_audit

Example

Complete Ratings for example.com

📊 Main Lighthouse Scores

⚡ Detailed Performance Metrics

♿ Detailed Accessibility Scores (92/100)

🏆 Detailed Best Practices Scores (96/100)

🔍 Detailed SEO Scores (100/100)

🔧 Main Performance Issues

📈 Network Metrics

💡 Priority Recommendations

🎯 Summary

Development

Logging / pino-pretty in MCP environments

Troubleshooting

"Google API key not provided"

"PageSpeed Insights API error: 403"

"Invalid URL"

Acknowledgments

License

Support

About

`analyze_page_speed`

`get_performance_summary`

`get_recommendations`

`clear_cache`

`get_visual_analysis`

`get_element_analysis`

`get_network_analysis`

`get_javascript_analysis`

`get_image_optimization_details`

`get_render_blocking_details`

`get_third_party_impact`

`get_full_audit`

Logging / `pino-pretty` in MCP environments

Packages