PageSpeed Insights MCP Server
Six-tool MCP server for Google PageSpeed Insights & Chrome UX Report APIs. Analyze, compare, and optimize web performance directly through Claude, Cursor, or any MCP-compatible AI client.
Potencia tu agente
El comando propio del publicador. No es un endpoint de PlugMCP.
Host a copy with our keys and logs.
npx -y [email protected]Claude Code no tiene enlace de instalación para un comando local. Copia el comando de abajo y ejecútalo en una terminal.
GOOGLE_API_KEY=<secret> claude mcp add ruslanlap-pagespeed-insights-mcp -- npx -y pagespeed-insights-mcp@2.2.0Ejecútalo en una terminal.
{ "mcpServers": { "ruslanlap-pagespeed-insights-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ], "env": { "GOOGLE_API_KEY": "<secret>" } } }}claude_desktop_config.json
¿URL remota o un comando en tu máquina? En qué se diferencian las dos instalaciones
Ejecutar en PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
AbrirDel publicador
Six-tool MCP server for Google PageSpeed Insights & Chrome UX Report APIs. Analyze, compare, and optimize web performance directly through Claude, Cursor, or any MCP-compatible AI client.
MCP server for Google PageSpeed Insights & Chrome UX Report APIs. Analyze, compare, and optimize web performance directly through Claude, Cursor, or any MCP-compatible AI client.
{
"mcpServers": {
"pagespeed-insights": {
"command": "npx",
"args": ["-y", "pagespeed-insights-mcp"],
"env": { "GOOGLE_API_KEY": "your-google-api-key" }
}
}
}
Get a free API key at Google Cloud Console → paste into Claude Desktop's claude_desktop_config.json → restart. Done. (Codex/OpenAI config, Docker)
Most PageSpeed MCP servers wrap one tool: "run PSI on a URL." This server ships six workflow tools covering the full performance workflow — not just a score, but an action plan:
🎬 View Interactive Demo → — See the tools in action with animated examples Fallback URL: https://ruslanlap.github.io/pagespeed-insights-mcp/demo.html
Add to your claude_desktop_config.json:
{
"mcpServers": {
"pagespeed-insights": {
"command": "npx",
"args": ["-y", "-p", "pino-pretty", "-p", "pagespeed-insights-mcp", "pagespeed-insights-mcp"],
"env": {
"GOOGLE_API_KEY": "your-google-api-key-here"
}
}
}
}
Add to your configuration (TOML):
[mcp_servers.pagespeed-insights]
command = "npx"
args = [
"-y",
"-p",
"pino-pretty",
"-p",
"pagespeed-insights-mcp",
"pagespeed-insights-mcp"
]
env = { GOOGLE_API_KEY = "your-google-api-key-here" }
Note: The
pino-prettypackage is required for proper log formatting. The above configurations ensure it is installed automatically vianpx.
Add to ~/.grok/config.toml (global) or <repo>/.grok/config.toml (project-scoped, higher priority):
[mcp_servers.pagespeed-insights]
command = "npx"
args = ["-y", "-p", "pino-pretty", "-p", "pagespeed-insights-mcp", "pagespeed-insights-mcp"]
env = { GOOGLE_API_KEY = "${GOOGLE_API_KEY}" }
enabled = true
# Recommended companion professional MCPs (add once):
# [mcp_servers.github] — PRs, issues, code search
# [mcp_servers.context7] — fresh library docs (Upstash)
# [mcp_servers.serena] — semantic code intelligence (uses your .serena/ if present)
Project-scoped example (put in this repo's .grok/config.toml for local dist/index.js + tighter Serena):
[mcp_servers.pagespeed-insights]
command = "node"
args = ["/home/ubuntuvm/Projects/pagespeed-insights-mcp/dist/index.js"]
env = { GOOGLE_API_KEY = "${GOOGLE_API_KEY}", NODE_ENV = "development" }
Verification inside Grok session:
/mcps (or Ctrl+L → MCP tab) → ensure pagespeed-insights shows "running"pagespeed-insights__pagespeed_analyze_page, pagespeed-insights__pagespeed_get_field_data, etc. (namespaced)Real pagespeed_analyze_page results for github.com — one mobile Lighthouse run. CrUX numbers come from pagespeed_get_field_data with scope: "origin":
Lighthouse lab scores:
Core metrics (mobile):
CrUX field data — real users, github.com origin (phone):
Results vary between runs — Lighthouse lab data is noisy (a single run is one sample). Use
runs: 3-5for medians.Lab vs field: Lighthouse throttles the connection (hence 54/100 mobile), while CrUX shows how actual GitHub visitors experience it — both views come straight from this server's tools.
We have comprehensive documentation available online.
You can also view the raw markdown files in the
docs/directory or runmkdocs servelocally.
Current release: see the version badges at the top of this README.
✨ Rich Aesthetic & Visual Formatters:
█████████████░░░ 85/100 🟢 Good) for instant visual feedback.🟢 Good, 🟡 Needs Improvement, 🔴 Poor).🔴 High | 🟡 Medium | 🟢 Low | Impact: High).💬 Native MCP Prompts (Slash Commands):
/performance-audit: Guided 4-step performance triage with prioritized remediation./release-comparison: Staging vs production delta verification with a clear GO / NO-GO decision./core-web-vitals-deepdive: Deep-dive contrasting real-user CrUX field data with synthetic Lighthouse lab simulations.📚 Native MCP Resources:
pagespeed://web-vitals-guide: 2026 Core Web Vitals thresholds and optimization playbooks.pagespeed://baselines: Locally recorded performance baselines for regression tracking.🧪 Enterprise-Grade Test Suite & Resilience:
100% on formatters, resources, and baselines).prepublishOnly (lint, typecheck, test, build).v2 Core Architecture:
pagespeed_* tools replace the former 19 v1 endpoint-shaped tools; all data tools support Markdown or JSON with structured results.The badges at the top of this README update automatically on every release (npm version, GitHub package version, downloads). No manual edits needed.
For the complete release history, see CHANGELOG.md.
Pain point 1 — "My page is slow but I don't know why." You open PageSpeed Insights, get a wall of data, and still can't tell what to fix first. This MCP gives your AI assistant six focused workflows that cut through the noise: it identifies the exact render-blocking resources, the specific images wasting 2 MB, the third-party scripts eating 1.5 s of main-thread time — and ranks them by impact. Ask "why is my site slow?" and get a prioritized fix list, not a 40-metric dashboard.
Pain point 2 — "I ship performance regressions to production." Your team moves fast, deploys daily, and nobody runs a full Lighthouse audit before each merge. By the time someone notices the Core Web Vitals dropped, the regression is already live. This MCP lets any developer paste a URL into Claude/Cursor and get a complete audit — lab data, field data from real Chrome users (CrUX), element-level CLS/LCP debugging — in seconds. It's the difference between catching a regression at your desk and discovering it in a Slack message from the SEO team three days later.
# Set environment variable
export GOOGLE_API_KEY=your-google-api-key
curl -sSL https://raw.githubusercontent.com/ruslanlap/pagespeed-insights-mcp/master/scripts/install.sh | bash
The installer uses the public npm package (pagespeed-insights-mcp) by default. To install the scoped GitHub Packages build instead, configure GitHub Packages authentication first and run:
curl -sSL https://raw.githubusercontent.com/ruslanlap/pagespeed-insights-mcp/master/scripts/install.sh | \
PAGESPEED_INSIGHTS_MCP_PACKAGE=@ruslanlap/pagespeed-insights-mcp bash
# Global installation from npm
npm install -g pagespeed-insights-mcp
# Or use without installation
npx pagespeed-insights-mcp
# First configure authentication (see GITHUB_PACKAGES.md for details)
# Then install globally
npm install -g @ruslanlap/pagespeed-insights-mcp
Note: This package is available on both npm and GitHub Packages.
- For npm: Use
npm install pagespeed-insights-mcp- For GitHub Packages: Use
npm install @ruslanlap/pagespeed-insights-mcp(requires GitHub authentication)For detailed instructions on installing from GitHub Packages, see GITHUB_PACKAGES.md or visit the GitHub Packages page
The MCP server requires a Google API key to access the PageSpeed Insights API.
# Set environment variable
export GOOGLE_API_KEY=your-google-api-key
# Windows
$env:GOOGLE_API_KEY="your-google-api-key"
# Or pass directly when running
GOOGLE_API_KEY=your-google-api-key npx pagespeed-insights-mcp
"pagespeed-insights": {
"command": "npx",
"args": [
"-y",
"-p",
"pino-pretty",
"-p",
"pagespeed-insights-mcp",
"pagespeed-insights-mcp"
],
"env": {
"GOOGLE_API_KEY": "your-google-api-key-here"
}
}
[mcp_servers.pagespeed-insights]
command = "npx"
args = [
"-y",
"-p",
"pino-pretty",
"-p",
"pagespeed-insights-mcp",
"pagespeed-insights-mcp"
]
env = { GOOGLE_API_KEY = "your-google-api-key-here" }
Note: These examples include
pino-prettyfor better log formatting. For production use without pretty logs, see the Logging section below.
Example configuration files are available in the examples directory.
docker build -t pagespeed-insights-mcp .
docker run -e GOOGLE_API_KEY=your-key pagespeed-insights-mcp
To use this MCP server, you need a Google API key with the PageSpeed Insights API enabled.
[!TIP] ⚡ Quick Setup Link: You can go directly to the Google Cloud Credentials Setup Page to quickly create a key in your project.
GOOGLE_API_KEY in your configuration.Config paths: macOS ~/Library/Application Support/Claude/claude_desktop_config.json · Windows %APPDATA%\Claude\claude_desktop_config.json · Linux ~/.config/claude/claude_desktop_config.json — see ⚙️ Client Configuration above for the JSON. Restart Claude Desktop after editing.
After configuration, simply ask Claude any of these commands:
Analyze the performance of https://example.com
Analyze https://example.com for mobile devices with all categories
Get a quick performance report for https://example.com
Analyze https://example.com performance for desktop devices
Perform a full audit of https://example.com including SEO, accessibility, and best practices
Get smart recommendations for improving https://example.com performance
Clear the cache to get fresh data for all subsequent requests
Get visual analysis for https://example.com showing screenshots and loading timeline
Show me which specific elements are causing performance issues on https://example.com
Analyze the network requests and resource loading for https://example.com
Get JavaScript execution breakdown for https://example.com
Show me which images need optimization on https://example.com
Find render-blocking resources on https://example.com
Analyze third-party script impact on https://example.com performance
Run a full audit including accessibility, SEO, and best practices for https://example.com
Version 2 replaces the former 19 endpoint-shaped tools with six workflow tools. This is a breaking change: update MCP client prompts, saved tool calls, and integrations to use the names below. Every data-returning tool accepts responseFormat (markdown, default, or json) and returns MCP structuredContent.
{"url":"https://example.com","strategy":"mobile","report":"recommendations","responseFormat":"markdown"}
{"url":"https://example.com","focus":"render-blocking","responseFormat":"json"}
{"mode":"baseline","url":"https://example.com","strategy":"mobile","runs":3}
answer example from Claude Desktop with pagespeed-insights-mcp 🔥🔥🔥
This server exposes built-in MCP Prompts that appear automatically in the prompt / slash menu (/) in Claude Desktop, Cursor, and Cline:
Access reference guides and local state directly through standard MCP resource URIs:
Outputs returned to Claude Desktop, Cursor, and Cline feature rich aesthetic formatting:
\█████████████░░░` 85/100 🟢 (Good)`).🟢 Good, 🟡 Needs Improvement, 🔴 Poor).[](https://pagespeed.web.dev)).For better log formatting during development, it is recommended to install pino-pretty globally:
npm install -g pino-pretty
# Development mode
npm run dev
# Build project
npm run build
# Run built server
npm start
pino-pretty in MCP environmentsThis MCP server uses pino for logging and enables the pino-pretty transport when NODE_ENV=development.
NODE_ENV=production GOOGLE_API_KEY=your-google-api-key npx pagespeed-insights-mcp
or in your MCP config:
"pagespeed-insights": {
"command": "npx",
"args": ["pagespeed-insights-mcp"],
"env": {
"GOOGLE_API_KEY": "your-google-api-key-here",
"NODE_ENV": "production"
}
}
npx, you can have npx install pino-pretty alongside the server:"pagespeed-insights": {
"command": "npx",
"args": [
"-y",
"-p",
"pino-pretty",
"-p",
"pagespeed-insights-mcp",
"pagespeed-insights-mcp"
],
"env": {
"GOOGLE_API_KEY": "your-google-api-key-here"
}
}
Ensure the GOOGLE_API_KEY environment variable is set in your Claude Desktop configuration.
Check if PageSpeed Insights API is enabled in your Google Cloud project.
Ensure the URL includes the protocol — only http:// and https:// are accepted. Other schemes (file://, ftp://, javascript:, etc.) are rejected at the schema level.
Please report security issues privately — do not open a public issue. See SECURITY.md for the disclosure policy and operator hardening notes.
Special thanks to @engmsaleh (Mohamed Saleh Zaied) for his significant contribution to the development of this project.
A very special thank you to @system-conf for their outstanding and invaluable contribution to the growth and development of this project. Your dedication, expertise, and continuous support have made a tremendous impact — this project wouldn't be where it is today without you. 🙏
Apache-2.0 — see LICENSE. Patents granted by contributors under the Apache License 2.0.
For bug reports or feature requests, please create an issue in the repository.
MCP server for Google PageSpeed Insights & Chrome UX Report APIs. Analyze, compare, and optimize web performance directly through Claude, Cursor, or any MCP-compatible AI client.
{ "mcpServers": { "ruslanlap-pagespeed-insights-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ], "env": { "GOOGLE_API_KEY": "<secret>" } } }}Herramientas
Aún no hay lista de herramientas. Los servidores remotos la reciben tras la primera comprobación de estado.
Preguntas frecuentes
Copia en esta página la configuración stdio para Cursor, Claude Desktop, Claude Code o VS Code. Usa la instalación del publicador, no un proxy de PlugMCP.
El publicador indica estas variables de entorno: GOOGLE_API_KEY.
Pagespeed Insights se ejecuta localmente por stdio.
Última comprobación: 2026-11-17. MCP server for Google PageSpeed Insights & Chrome UX Report APIs. Analyze, compare, and optimize web performance directly through Claude, Cursor, or any MCP-compatible AI client.