# PageSpeed Insights MCP Server

FastMCP server for Google PageSpeed Insights analysis through the PageSpeed Insights REST API.

## Features

- Run PageSpeed Insights analysis for desktop or mobile.
- Return compact summaries with Lighthouse category scores, core metrics, field data, opportunities, warnings, and failed audits.
- Compare mobile and desktop results.
- List performance opportunities sorted by estimated savings.
- Fetch a specific Lighthouse audit by id, including its full details payload.
- Expose local API metadata and supported categories/strategies.

## Google API endpoint

This server calls:

```
GET https://pagespeedonline.googleapis.com/pagespeedonline/v5/runPagespeed
```

The required query parameter is `url`. Optional parameters used by this server include `strategy`, repeated `category`, `locale`, `captchaToken`, and `key`.

API docs:

- https://developers.google.com/speed/docs/insights/rest
- https://developers.google.com/speed/docs/insights/rest/v5/pagespeedapi/runpagespeed

## Create `.env` file

An API key is optional for trial calls, but recommended for repeated automated usage.

```
# Optional
PAGESPEED_API_KEY=google_api_key_here

# Optional alternative key name
GOOGLE_API_KEY=google_api_key_here

# Optional
PAGESPEED_API_URL=https://pagespeedonline.googleapis.com
PAGESPEED_TIMEOUT_SECONDS=120
```

## Tools

### `get_pagespeed_api_metadata`

Returns endpoint details, whether an API key is configured, supported strategies, supported categories, aliases, and documentation links.

### `run_pagespeed`

Runs PageSpeed analysis for a URL.

Parameters:

- `url`: URL to analyze. Must start with `http://`, `https://`, `url:http(s)://`, or `origin:http(s)://`.
- `strategy`: `DESKTOP` or `MOBILE`. Defaults to `DESKTOP`.
- `categories`: optional list. Supported values: `PERFORMANCE`, `ACCESSIBILITY`, `BEST_PRACTICES`, `SEO`, `PWA`, or `all`.
- `locale`: optional locale such as `en-US`.
- `utm_campaign`: optional campaign name for analytics.
- `utm_source`: optional campaign source for analytics.
- `captcha_token`: optional captcha token.
- `full_response`: return the full Google API JSON response when true.
- `api_key`: optional per-call API key override.

### `analyze_url`

Runs analysis and returns a compact report. By default it runs performance, accessibility, best practices, and SEO.

### `compare_mobile_desktop`

Runs mobile and desktop analysis for the same URL and returns score deltas.

### `list_opportunities`

Runs performance analysis and returns opportunity audits sorted by estimated savings.

### `get_lighthouse_audit`

Returns one Lighthouse audit by audit id. Use `categories=["all"]` if the audit may not be part of the Performance category.

## Create a virtual environment

```
cd PROJECT_FOLDER
python3 -m venv .venv
```

## Activate it

```
source .venv/bin/activate
```

## Install dependencies

```
pip install fastmcp requests python-dotenv
```

## Freeze the requirements

```
pip freeze > requirements.txt
```

## Test it

```
python3 server.py
```

You should see:

`Starting MCP server 'pagespeed-insights-mcp-server' with transport 'stdio'`

## Configure OpenCode

```
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "pagespeed-insights": {
      "type": "local",
      "command": [
        "PATH_TO_YOUR_MCP_PROJECT/.venv/bin/python",
        "PATH_TO_YOUR_MCP_PROJECT/server.py"
      ],
      "enabled": true
    }
  }
}
```

## Docker / HTTP mode

```
docker compose up --build
```

HTTP mode listens on port `8004`.

Docker Compose reads values from `.env` automatically when the file exists, but the container can run without one for unauthenticated trial calls.