# MCP PageSpeed Insights

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that connects LLMs to [Google PageSpeed Insights](https://developers.google.com/speed/docs/insights/v5/about). It lets AI assistants analyze any web page's performance, accessibility, SEO, and best practices — then help you act on the results.

## Prerequisites

- **Node.js 18+**
- **Google API Key** — get one for free at [Google Developers Console](https://developers.google.com/speed/docs/insights/v5/get-started#key)

## Setup

```bash
git clone https://github.com/NicolasET/mcp-pagespeed-insight.git
cd mcp-pagespeed-insight
npm install
npm run build
```

## Configuration

Add the server to your MCP client.

### Claude Code (CLI)

```bash
claude mcp add pagespeed-insights -e GOOGLE_API_KEY=your_api_key_here -- node /absolute/path/to/mcp-pagespeed-insights/dist/server.js
```

On **Windows** (outside WSL), wrap with `cmd /c`:

```bash
claude mcp add pagespeed-insights -e GOOGLE_API_KEY=your_api_key_here -- cmd /c node C:\absolute\path\to\mcp-pagespeed-insights\dist\server.js
```

**Scope options** (add `--scope` before the server name):

| Scope | Description |
|---|---|
| `local` (default) | Private to you, current project only |
| `project` | Shared with the team via `.mcp.json` (committed to version control) |
| `user` | Private to you, available across all projects |

Example with scope:

```bash
claude mcp add --scope user pagespeed-insights -e GOOGLE_API_KEY=your_api_key_here -- node /absolute/path/to/mcp-pagespeed-insights/dist/server.js
```

After adding, verify with:

```bash
claude mcp list
```

### Claude Desktop

Edit `claude_desktop_config.json` (Settings > Developer > Edit Config):

```json
{
  "mcpServers": {
    "pagespeed-insights": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-pagespeed-insights/dist/server.js"],
      "env": {
        "GOOGLE_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

### Other MCP clients (Cursor, Windsurf, etc.)

Refer to your client's docs for registering a stdio MCP server. The command is:

```
node /absolute/path/to/mcp-pagespeed-insights/dist/server.js
```

The `GOOGLE_API_KEY` environment variable must be set.

## Available Tools

| Tool | Description |
|---|---|
| `analyze_url` | Full Lighthouse analysis — all category scores, key metrics, and top improvement opportunities |
| `get_performance_metrics` | Core Web Vitals and performance scores (LCP, CLS, TBT, FCP, SI, TTI, TTFB) |
| `get_recommendations` | Prioritized improvement opportunities sorted by estimated impact |
| `get_network_analysis` | Resource breakdown by type, transfer sizes, and largest resources |
| `get_js_analysis` | JavaScript boot-up time, main thread work, and unused code |
| `get_image_optimization` | Images needing compression, modern format conversion, or lazy-loading |
| `get_render_blocking` | Render-blocking CSS/JS, critical request chains, preconnect/preload opportunities |
| `get_third_party_impact` | Third-party scripts by provider, size, blocking time, and facade opportunities |
| `get_accessibility_issues` | Accessibility score and all failing audits with affected elements |
| `compare_strategies` | Side-by-side mobile vs desktop comparison of scores and metrics |

All tools accept a `url` parameter (required) and a `strategy` parameter (`mobile` or `desktop`, defaults to `mobile`). The `analyze_url` and `compare_strategies` tools also accept a `categories` array to select which Lighthouse categories to run.

## Environment Variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `GOOGLE_API_KEY` | Yes | — | Your Google API key for PageSpeed Insights |
| `CACHE_TTL_MS` | No | `300000` (5 min) | How long to cache API responses in milliseconds |

## Example Usage

Once configured, you can ask your AI assistant things like:

- *"Analyze the performance of https://example.com"*
- *"What are the biggest performance issues on my site and how can I fix them?"*
- *"Compare mobile vs desktop performance for https://example.com"*
- *"Which images on https://example.com need optimization?"*
- *"Are there any accessibility issues on https://example.com?"*
- *"What third-party scripts are slowing down https://example.com?"*

## Development

```bash
# Run in development mode (no build needed)
npm run dev

# Type-check without emitting
npm run typecheck

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Build for production
npm run build
```

## License

[MIT](LICENSE)