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.

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

💻 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

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

Example configuration files are available in the examples directory.

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

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

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

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

Troubleshooting