# PageSpeed Insights MCP Server

An MCP server that wraps the [Google PageSpeed Insights API v5](https://developers.google.com/speed/docs/insights/v5/get-started), 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](https://console.cloud.google.com/).
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](https://console.cloud.google.com/iam-admin/quotas).

---

## Step 2 — Install

### With `pip` (virtualenv recommended)

```bash
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)

```bash
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:

```bash
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:

```bash
# 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

```bash
# 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`

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

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

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

```bash
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)

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

### 2. Quick Core Web Vitals check

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

### 3. Opportunities with minimum savings

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

### 4. Diagnostics

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

### 5. Mobile vs Desktop comparison (JSON output)

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

### 6. Batch analysis

```json
{
  "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

```json
{
  "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` |