pagespeed-insights

The PageSpeed Insights MCP Server exposes Google's PageSpeed Insights capabilities through Claude, enabling you to run performance analyses and access detailed Lighthouse reports directly from the chat interface. It supports rich output such as visual analysis (screenshots, filmstrip, full-page captures), element-level debugging, a network waterfall, JavaScript profiling, image optimization insights, render-blocking analysis, and third-party impact assessments, all wrapped into a single MCP server you can query via Claude prompts. To start using it, configure the MCP with your Google API key and invoke the server by selecting the pagespeed-insights MCP and running commands that leverage the server’s tools. The included pino-pretty logging option ensures readable, nicely formatted logs during operation. The integration makes it easy to obtain actionable performance recommendations and automated audits from PageSpeed Insights within Claude conversations. The server is designed for multi-platform usage, supporting mobile and desktop perspectives and providing quick installation for rapid experimentation.

In practice, you can request specific outputs such as Lighthouse audits, render-blocking analysis, or third-party script impact, and the MCP will return structured results and guidance tailored to those facets. It also offers visual captures and performance breakdowns to help you pinpoint optimization opportunities.

Prerequisites:

• Node.js and npm installed on your system (or a compatible environment that supports npx).
• A Google API key with access to the PageSpeed Insights API.
• Optional: Docker if you prefer containerized deployment.

Option A: Quick start with npm/npx (recommended for local development)

1. Install Node.js and npm from https://nodejs.org/
2. Export your Google API key:
   • Linux/macOS: export GOOGLE_API_KEY=your-google-api-key
   • Windows (PowerShell): $env:GOOGLE_API_KEY = "your-google-api-key"
3. Run the MCP server via npx (no permanent install required): npx -y -p pino-pretty -p pagespeed-insights-mcp pagespeed-insights-mcp
4. Ensure the environment variable GOOGLE_API_KEY is available to the process (the command above includes it in MCP config).

Option B: Docker deployment

1. Build the Docker image: docker build -t pagespeed-insights-mcp .
2. Run the container with your API key: docker run -e GOOGLE_API_KEY=your-google-api-key -p 8080:8080 pagespeed-insights-mcp (Adjust port mappings as needed.)

Option C: Claude Desktop or Codex integration

1. Use the provided MCP configuration (see mcp_config section) and insert your GOOGLE_API_KEY.
2. If you want to log nicely in development, enable pino-pretty by including it in the npx args as shown in the configuration example.

Prerequisites summary

• A valid Google API key configured for PageSpeed Insights API
• Node.js/npx or Docker for deployment
• Optional: pino-pretty for readable logs

Tips and common issues:

• GOOGLE_API_KEY is required; without it, requests to PageSpeed Insights will fail. Ensure the key has the necessary API access enabled.
• If you prefer production-grade logging without pretty output, you can omit pino-pretty from the args. In that case, logs may be more verbose but faster.
• Docker users can customize environment variables or mount configuration as needed. The example uses a direct GOOGLE_API_KEY environment variable.
• The MCP configuration examples show both Claude Desktop (JSON) and Codex (TOML) formats. Ensure you place the configuration in the correct editor for your workflow.
• The npm package is pagespeed-insights-mcp; you can install globally or use npx for quick execution. If you plan to deploy in production, consider a proper process manager and environment isolation.
• If you encounter rate limits or API quota issues, monitor your PageSpeed Insights quota and consider caching results where appropriate via the MCP's caching capabilities.