PageSpeed Insights MCP Server

An MCP server that wraps the Google PageSpeed Insights API v5, exposing 7 focused tools for analysing web performance — scores, Core Web Vitals, opportunities, diagnostics, and batch analysis.

PWA Category Notice: The pwa Lighthouse category was removed in Lighthouse 12+ and is no longer available via the PSI API. Requesting it returns an API error. psi_check_pwa is intentionally not implemented.

---

Features

Tool	Description
psi_analyze_url	Full analysis — scores + CWV + top-5 opportunities
psi_get_core_web_vitals	Lightweight CrUX field data + lab CWV
psi_get_opportunities	Opportunities sorted by estimated savings
psi_get_diagnostics	Diagnostic issues (DOM size, JS work, etc.)
psi_compare_mobile_desktop	Side-by-side mobile vs desktop comparison
psi_batch_analyze	Analyse up to 10 URLs, partial-failure tolerant
psi_get_category_score	Single category score + audit breakdown

---

Prerequisites

• Python 3.11+
• A Google API key with the PageSpeed Insights API enabled

---

Step 1 — Get a Google API Key

1. Go to the Google Cloud Console.
2. Create or select a project.
3. Navigate to APIs & Services → Library and search for "PageSpeed Insights API".
4. Click Enable.
5. Go to APIs & Services → Credentials → Create Credentials → API key.
6. Copy the generated key.

Quota: 25,000 requests/day · 400 requests/100 seconds per API key.
To request higher limits: Cloud Console → IAM & Admin → Quotas.

---

Step 2 — Install

With pip (virtualenv recommended)

cd page-speed-insights-mcp
python -m venv .venv

# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

pip install -r requirements.txt

With uv (recommended)

cd page-speed-insights-mcp
uv venv
uv pip install -r requirements.txt

---

Step 3 — Set PSI_API_KEY

Copy the example file and add your key:

cp .env.example .env

Edit .env:

PSI_API_KEY=AIzaSy...your_key_here

The server loads this automatically via python-dotenv. Alternatively, export it directly:

# Windows PowerShell
$env:PSI_API_KEY = "AIzaSy..."

# macOS/Linux
export PSI_API_KEY="AIzaSy..."

Security: Never commit your .env file or hardcode your API key in source code.

---

Step 4 — Verify the Installation

# Syntax check all modules
python -m py_compile pagespeed_mcp/server.py
python -m py_compile pagespeed_mcp/api.py
python -m py_compile pagespeed_mcp/models.py
python -m py_compile pagespeed_mcp/formatters.py
echo "All files compiled OK"

---

Step 5 — Register with Claude Desktop

Edit your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "pagespeed": {
      "command": "python",
      "args": ["-m", "pagespeed_mcp.server"],
      "cwd": "D:/SIVA/mcps/page-speed-insights-mcp",
      "env": {
        "PSI_API_KEY": "AIzaSy...your_key_here"
      }
    }
  }
}

Tip: Use the full path to the Python executable inside your virtualenv instead of bare python to avoid PATH issues:

• Windows: "D:/SIVA/mcps/page-speed-insights-mcp/.venv/Scripts/python.exe"
• macOS/Linux: "/path/to/page-speed-insights-mcp/.venv/bin/python"

---

Step 6 — Register with Claude Code

In your project's .claude/settings.json or ~/.claude/settings.json:

{
  "mcpServers": {
    "pagespeed": {
      "command": "python",
      "args": ["-m", "pagespeed_mcp.server"],
      "cwd": "D:/SIVA/mcps/page-speed-insights-mcp",
      "env": {
        "PSI_API_KEY": "AIzaSy...your_key_here"
      }
    }
  }
}

Or add via CLI:

claude mcp add pagespeed python -m pagespeed_mcp.server \
  --cwd "D:/SIVA/mcps/page-speed-insights-mcp" \
  --env PSI_API_KEY=AIzaSy...

---

Step 7 — Test with MCP Inspector

npx @modelcontextprotocol/inspector python -m pagespeed_mcp.server

This opens a browser UI where you can call each tool interactively.

---

Example Tool Calls

1. Full analysis (Markdown)

{
  "tool": "psi_analyze_url",
  "arguments": {
    "url": "https://web.dev",
    "strategy": "mobile",
    "categories": ["performance", "accessibility", "seo"]
  }
}

2. Quick Core Web Vitals check

{
  "tool": "psi_get_core_web_vitals",
  "arguments": {
    "url": "https://www.google.com",
    "strategy": "desktop"
  }
}

3. Opportunities with minimum savings

{
  "tool": "psi_get_opportunities",
  "arguments": {
    "url": "https://example.com",
    "strategy": "mobile",
    "min_savings_ms": 200
  }
}

4. Diagnostics

{
  "tool": "psi_get_diagnostics",
  "arguments": {
    "url": "https://example.com",
    "strategy": "mobile"
  }
}

5. Mobile vs Desktop comparison (JSON output)

{
  "tool": "psi_compare_mobile_desktop",
  "arguments": {
    "url": "https://web.dev",
    "response_format": "json"
  }
}

6. Batch analysis

{
  "tool": "psi_batch_analyze",
  "arguments": {
    "urls": [
      "https://web.dev",
      "https://www.google.com",
      "https://github.com"
    ],
    "strategy": "mobile",
    "categories": ["performance", "seo"]
  }
}

7. Single category score

{
  "tool": "psi_get_category_score",
  "arguments": {
    "url": "https://example.com",
    "category": "accessibility",
    "strategy": "desktop"
  }
}

---

Caching

Repeated calls for the same (url, strategy, categories) within a 5-minute window return cached results, avoiding unnecessary API quota consumption. The cache is in-memory and resets when the server restarts.

---

Rate Limits & Best Practices

Limit	Value
Requests per day	25,000
Requests per 100 seconds	400

• Use psi_get_core_web_vitals for quick health checks (only fetches performance category).
• In batch mode, specify only the categories you need to reduce response time.
• The 5-minute cache prevents redundant calls in a single session.
• On HTTP 429, the server automatically retries up to 3 times with back-off.

---

Project Structure

page-speed-insights-mcp/
├── pagespeed_mcp/
│   ├── __init__.py       # Package marker
│   ├── server.py         # FastMCP app + 7 tool definitions
│   ├── api.py            # HTTP client, cache, retry, error handling
│   ├── models.py         # Pydantic v2 input models
│   └── formatters.py     # Response extractors and Markdown/JSON renderers
├── requirements.txt
├── .env.example
└── README.md

---

Troubleshooting

Error	Fix
❌ Missing API key	Set PSI_API_KEY in .env or environment
❌ API key rejected (HTTP 403)	Verify the key is valid and PageSpeed Insights API is enabled in your Cloud project
❌ Invalid URL (HTTP 400)	Ensure the URL is publicly accessible and starts with https://
⏳ Rate limited (HTTP 429)	Reduce request frequency; the server retries automatically up to 3 times
⏱️ Request timed out	The page may be unreachable or very slow; try again
pwa category error	PWA category was removed from Lighthouse 12+ — do not pass pwa