PageSpeed Insights MCP

Requirements

• Node.js 20 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.

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

🚀 Quick Installation

Option 1: Automatic Installation (Recommended)

```bash

Global installation from npm

npm install -g pagespeed-insights-mcp

Or use without installation

npx pagespeed-insights-mcp

#### From GitHub Packages

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

Option 3: Docker

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

Build project

npm run build

⚡ Quick Start (Copy & Paste)

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

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

<p align="center"> <img src="assets/3.png" alt="Google Cloud Console API Key Setup" width="90%" /> </p>

💻 Usage

After configuration, simply ask Claude any of these commands:

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:

Set environment variable

export GOOGLE_API_KEY=your-google-api-key

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:

Option 2: Via npm or GitHub Packages

From npm (Public Registry)

```bash

First configure authentication (see GITHUB_PACKAGES.md for details)

🔧 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

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

⚙️ 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!

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

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

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

CrUX & Comparison

`compare_pages`

Compare performance metrics between two URLs side-by-side.

Parameters:

• urlA (required): First URL to compare
• urlB (required): Second URL to compare
• strategy: "mobile" or "desktop" (default: "mobile")

Returns:

• Side-by-side Lighthouse score comparison
• Metric-level diff for LCP, CLS, FCP, TBT, SI
• Winner/loser indication per metric

Troubleshooting