MCP PageSpeed Insights

An MCP (Model Context Protocol) server that connects LLMs to Google PageSpeed Insights. 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

Setup

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)

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:

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:

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:

claude mcp list

Claude Desktop

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

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

# 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