# pagespeed-insights-mcp [Health: Active] **Category:** ๐Ÿ’ป Developer Tools **Repository:** https://github.com/ruslanlap/pagespeed-insights-mcp **GitHub Stars:** 58 **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/pagespeed-insights-mcp-2 ## Description Google PageSpeed Insights & CrUX APIs: 16 tools for web performance audits. ## Claude Desktop Quick Installation Install path detected from listing signals. Uses `npx` (confidence: high): ```json "mcpServers": { "pagespeed-insights-mcp": { "command": "npx", "args": ["-y","pagespeed-insights-mcp"] } } ``` ## Documentation & README # PageSpeed Insights MCP Server [![Buy Me A Coffee](https://img.shields.io/badge/Buy_Me_A_Coffee-%40ruslanlap-FFDD00?style=flat-square&logo=buy-me-a-coffee&logoColor=black)](https://ruslanlap.github.io/ruslanlap_buymeacoffe/) **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) ```json { "mcpServers": { "pagespeed-insights": { "command": "npx", "args": ["-y", "pagespeed-insights-mcp"], "env": { "GOOGLE_API_KEY": "your-google-api-key" } } } } ``` Get a free API key at [Google Cloud Console](https://developers.google.com/speed/docs/insights/v5/get-started) โ†’ paste into Claude Desktop's `claude_desktop_config.json` โ†’ restart. Done. ([Codex/OpenAI config](#codex--openai), [Docker](#option-3-docker)) [![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) [![MCP Toplist](https://mcptoplist.com/badge/io.github.ruslanlap%2Fpagespeed-insights-mcp.svg)](https://mcptoplist.com/server/io.github.ruslanlap%2Fpagespeed-insights-mcp) [![Glama MCP](https://glama.ai/mcp/servers/ruslanlap/pagespeed-insights-mcp/badge)](https://glama.ai/mcp/servers/ruslanlap/pagespeed-insights-mcp)

PageSpeed MCP chat demo PageSpeed MCP terminal demo

[![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: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) ## ๐Ÿ”ฅ 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](https://registry.modelcontextprotocol.io/) and [Glama](https://glama.ai/mcp/servers), CI-tested with Vitest > **๐ŸŽฌ [View Interactive Demo โ†’](https://ruslanlap.github.io/pagespeed-insights-mcp/demo/)** โ€” See the 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) - [๐Ÿ”ฅ What Makes It Different](#-what-makes-it-different) - [โš™๏ธ Client Configuration](#-client-configuration) - [๐Ÿ“Š Example Output](#-example-output) - [๐Ÿ“š Documentation](#-documentation) - [๐Ÿ“ Release Notes](#-release-notes) - [๐ŸŽฏ Why You Need This](#-why-you-need-this) - [โœจ Features](#-features) - [๐Ÿš€ Quick Installation](#-quick-installation) - [๐Ÿ”‘ Getting Google API Key](#-getting-google-api-key) - [โš™๏ธ Claude Desktop Configuration](#-claude-desktop-configuration) - [๐Ÿ’ป Usage](#-usage) - [Available Tools](#available-tools) - [Development](#development) - [Troubleshooting](#troubleshooting) - [Requirements](#requirements) - [Security](#security) - [Acknowledgments](#acknowledgments) - [License](#license) - [Support](#support) ## โš™๏ธ Client Configuration ### 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 `/.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__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**](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: **v2.0.0**. Recent highlights: - **v2.0.0** โ€” six workflow-oriented `pagespeed_*` tools replace the 19 v1 endpoint-shaped tools; all data tools support Markdown or JSON with structured results. > 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`](https://github.com/ruslanlap/pagespeed-insights-mcp/blob/HEAD/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 six focused workflows 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** - Complete Lighthouse audits for all categories ## ๐Ÿš€ Quick Installation ### Option 1: Automatic Installation (Recommended) ```bash # Set environment variable export GOOGLE_API_KEY=your-google-api-key ``` ```bash 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: ```bash 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) ```bash # Global installation from npm npm install -g pagespeed-insights-mcp # Or use without installation npx pagespeed-insights-mcp ``` #### From GitHub Packages ```bash # 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 [GITHUB_PACKAGES.md](https://github.com/ruslanlap/pagespeed-insights-mcp/blob/HEAD/GITHUB_PACKAGES.md) or visit the [GitHub Packages page](https://github.com/ruslanlap/pagespeed-insights-mcp/pkgs/npm/pagespeed-insights-mcp) ### ๐Ÿ”ง Configuration The MCP server requires a Google API key to access the PageSpeed Insights API. ```bash # 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): ```json "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): ```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:** 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. ### Google Antigravity Example configuration files are available in the [examples](https://github.com/ruslanlap/pagespeed-insights-mcp/blob/HEAD/examples/) directory. ### Option 3: Docker ```bash 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](https://console.cloud.google.com/apis/credentials/key/)** to quickly create a key in your project. ### Step-by-Step Guide 1. Go to the [Google Cloud Console](https://console.cloud.google.com/) (or use the [Quick Setup Link](https://console.cloud.google.com/apis/credentials/key/)). 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**. 4. 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.

Google Cloud Console API Key Setup

## โš™๏ธ Claude Desktop Configuration Config paths: **macOS** `~/Library/Application Support/Claude/claude_desktop_config.json` ยท **Windows** `%APPDATA%\Claude\claude_desktop_config.json` ยท **Linux** `~/.config/claude/claude_desktop_config.json` โ€” see [โš™๏ธ Client Configuration](#๏ธ-client-configuration) above for the JSON. **Restart Claude Desktop** after editing. ## ๐Ÿ’ป 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 (v2) Version 2 replaces the former 19 endpoint-shaped tools with six workflow tools. This is a **breaking change**: update MCP client prompts, saved tool calls, and integrations to use the names below. Every data-returning tool accepts `responseFormat` (`markdown`, default, or `json`) and returns MCP `structuredContent`. | Tool | Use it for | |---|---| | `pagespeed_analyze_page` | One-page Lighthouse health check, full report, recommendations, audit findings, or a Mermaid map (`report`). | | `pagespeed_diagnose_page` | One focused investigation: `visual`, `elements`, `network`, `javascript`, `images`, `render-blocking`, or `third-parties`. | | `pagespeed_get_field_data` | CrUX real-user Core Web Vitals for a `page` or `origin`. | | `pagespeed_compare_pages` | Compare two pages now, or compare one page with its saved baseline (`mode`). | | `pagespeed_analyze_batch` | Triage 1โ€“10 pages with progress notifications when supported. | | `pagespeed_clear_cache` | Clear this process's in-memory API cache after a deploy. | ### Migration from v1 | v1 tools | v2 replacement | |---|---| | `analyze_page_speed`, `get_performance_summary`, `get_recommendations`, `get_full_audit`, `get_performance_map` | `pagespeed_analyze_page` with `report=full`, `summary`, `recommendations`, `audit`, or `performance-map` | | `get_visual_analysis`, `get_element_analysis`, `get_network_analysis`, `get_javascript_analysis`, `get_image_optimization_details`, `get_render_blocking_details`, `get_third_party_impact` | `pagespeed_diagnose_page` with the matching `focus` | | `crux_summary`, `get_origin_crux` | `pagespeed_get_field_data` with `scope=page` or `origin` | | `compare_pages`, `compare_baseline` | `pagespeed_compare_pages` with `mode=pages` or `baseline` | | `batch_analyze`, `clear_cache` | `pagespeed_analyze_batch`, `pagespeed_clear_cache` | | `full_report` | Run `pagespeed_analyze_page` and `pagespeed_get_field_data`; lab and field data stay explicit rather than being mixed. | ### Examples ```json {"url":"https://example.com","strategy":"mobile","report":"recommendations","responseFormat":"markdown"} ``` ```json {"url":"https://example.com","focus":"render-blocking","responseFormat":"json"} ``` ```json {"mode":"baseline","url":"https://example.com","strategy":"mobile","runs":3} ``` ### Example answer example from Claude Desktop with pagespeed-insights-mcp ๐Ÿ”ฅ๐Ÿ”ฅ๐Ÿ”ฅ ## Development For better log formatting during development, it is recommended to install `pino-pretty` globally: ```bash npm install -g pino-pretty ``` ```bash # 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: ```bash NODE_ENV=production GOOGLE_API_KEY=your-google-api-key npx pagespeed-insights-mcp ``` or in your MCP config: ```jsonc "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: ```jsonc "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 โ€” only `http://` and `https://` are accepted. Other schemes (`file://`, `ftp://`, `javascript:`, etc.) are rejected at the schema level. ## Requirements - Node.js **20.19.0 or later** (Node 18 is EOL since April 2025 and is no longer supported). - A Google API key with PageSpeed Insights and (optionally) Chrome UX Report APIs enabled. ## Security Please report security issues privately โ€” do **not** open a public issue. See [SECURITY.md](https://github.com/ruslanlap/pagespeed-insights-mcp/blob/HEAD/SECURITY.md) for the disclosure policy and operator hardening notes. ## Acknowledgments Special thanks to [@engmsaleh](https://github.com/engmsaleh) (Mohamed Saleh Zaied) for his significant contribution to the development of this project. A very special thank you to [@system-conf](https://github.com/system-conf) for their outstanding and invaluable contribution to the growth and development of this project. Your dedication, expertise, and continuous support have made a tremendous impact โ€” this project wouldn't be where it is today without you. ๐Ÿ™ ## License Apache-2.0 โ€” see [LICENSE](https://github.com/ruslanlap/pagespeed-insights-mcp/blob/HEAD/LICENSE). Patents granted by contributors under the Apache License 2.0. ## Support For bug reports or feature requests, please create an issue in the repository.