PageSpeed Insights MCP Server
Leverages Lighthouse audit data from the PageSpeed Insights API to surface performance scores, opportunities, and diagnostic issues (note: the PWA category was removed in Lighthouse 12+).
Provides tools for analysing web page performance via the Google PageSpeed Insights API, including full scores, Core Web Vitals, opportunities, diagnostics, mobile vs desktop comparison, batch analysis, and per-category scores.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
PageSpeed Insights MCP Server
An MCP server that wraps the Google PageSpeed Insights API v5, exposing 7 focused tools for analysing web performance — scores, Core Web Vitals, opportunities, diagnostics, and batch analysis.
PWA Category Notice: The
pwaLighthouse category was removed in Lighthouse 12+ and is no longer available via the PSI API. Requesting it returns an API error.psi_check_pwais intentionally not implemented.
Features
Tool | Description |
| Full analysis — scores + CWV + top-5 opportunities |
| Lightweight CrUX field data + lab CWV |
| Opportunities sorted by estimated savings |
| Diagnostic issues (DOM size, JS work, etc.) |
| Side-by-side mobile vs desktop comparison |
| Analyse up to 10 URLs, partial-failure tolerant |
| Single category score + audit breakdown |
Related MCP server: MCP Server Pagespeed
Prerequisites
Python 3.11+
A Google API key with the PageSpeed Insights API enabled
Step 1 — Get a Google API Key
Go to the Google Cloud Console.
Create or select a project.
Navigate to APIs & Services → Library and search for "PageSpeed Insights API".
Click Enable.
Go to APIs & Services → Credentials → Create Credentials → API key.
Copy the generated key.
Quota: 25,000 requests/day · 400 requests/100 seconds per API key.
To request higher limits: Cloud Console → IAM & Admin → Quotas.
Step 2 — Install
With pip (virtualenv recommended)
cd page-speed-insights-mcp
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate
pip install -r requirements.txtWith uv (recommended)
cd page-speed-insights-mcp
uv venv
uv pip install -r requirements.txtStep 3 — Set PSI_API_KEY
Copy the example file and add your key:
cp .env.example .envEdit .env:
PSI_API_KEY=AIzaSy...your_key_hereThe server loads this automatically via python-dotenv. Alternatively, export it directly:
# Windows PowerShell
$env:PSI_API_KEY = "AIzaSy..."
# macOS/Linux
export PSI_API_KEY="AIzaSy..."Security: Never commit your
.envfile or hardcode your API key in source code.
Step 4 — Verify the Installation
# Syntax check all modules
python -m py_compile pagespeed_mcp/server.py
python -m py_compile pagespeed_mcp/api.py
python -m py_compile pagespeed_mcp/models.py
python -m py_compile pagespeed_mcp/formatters.py
echo "All files compiled OK"Step 5 — Register with Claude Desktop
Edit your Claude Desktop config file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"pagespeed": {
"command": "python",
"args": ["-m", "pagespeed_mcp.server"],
"cwd": "D:/SIVA/mcps/page-speed-insights-mcp",
"env": {
"PSI_API_KEY": "AIzaSy...your_key_here"
}
}
}
}Tip: Use the full path to the Python executable inside your virtualenv instead of bare
pythonto avoid PATH issues:
Windows:
"D:/SIVA/mcps/page-speed-insights-mcp/.venv/Scripts/python.exe"macOS/Linux:
"/path/to/page-speed-insights-mcp/.venv/bin/python"
Step 6 — Register with Claude Code
In your project's .claude/settings.json or ~/.claude/settings.json:
{
"mcpServers": {
"pagespeed": {
"command": "python",
"args": ["-m", "pagespeed_mcp.server"],
"cwd": "D:/SIVA/mcps/page-speed-insights-mcp",
"env": {
"PSI_API_KEY": "AIzaSy...your_key_here"
}
}
}
}Or add via CLI:
claude mcp add pagespeed python -m pagespeed_mcp.server \
--cwd "D:/SIVA/mcps/page-speed-insights-mcp" \
--env PSI_API_KEY=AIzaSy...Step 7 — Test with MCP Inspector
npx @modelcontextprotocol/inspector python -m pagespeed_mcp.serverThis opens a browser UI where you can call each tool interactively.
Example Tool Calls
1. Full analysis (Markdown)
{
"tool": "psi_analyze_url",
"arguments": {
"url": "https://web.dev",
"strategy": "mobile",
"categories": ["performance", "accessibility", "seo"]
}
}2. Quick Core Web Vitals check
{
"tool": "psi_get_core_web_vitals",
"arguments": {
"url": "https://www.google.com",
"strategy": "desktop"
}
}3. Opportunities with minimum savings
{
"tool": "psi_get_opportunities",
"arguments": {
"url": "https://example.com",
"strategy": "mobile",
"min_savings_ms": 200
}
}4. Diagnostics
{
"tool": "psi_get_diagnostics",
"arguments": {
"url": "https://example.com",
"strategy": "mobile"
}
}5. Mobile vs Desktop comparison (JSON output)
{
"tool": "psi_compare_mobile_desktop",
"arguments": {
"url": "https://web.dev",
"response_format": "json"
}
}6. Batch analysis
{
"tool": "psi_batch_analyze",
"arguments": {
"urls": [
"https://web.dev",
"https://www.google.com",
"https://github.com"
],
"strategy": "mobile",
"categories": ["performance", "seo"]
}
}7. Single category score
{
"tool": "psi_get_category_score",
"arguments": {
"url": "https://example.com",
"category": "accessibility",
"strategy": "desktop"
}
}Caching
Repeated calls for the same (url, strategy, categories) within a 5-minute window return cached results, avoiding unnecessary API quota consumption. The cache is in-memory and resets when the server restarts.
Rate Limits & Best Practices
Limit | Value |
Requests per day | 25,000 |
Requests per 100 seconds | 400 |
Use
psi_get_core_web_vitalsfor quick health checks (only fetchesperformancecategory).In batch mode, specify only the categories you need to reduce response time.
The 5-minute cache prevents redundant calls in a single session.
On HTTP 429, the server automatically retries up to 3 times with back-off.
Project Structure
page-speed-insights-mcp/
├── pagespeed_mcp/
│ ├── __init__.py # Package marker
│ ├── server.py # FastMCP app + 7 tool definitions
│ ├── api.py # HTTP client, cache, retry, error handling
│ ├── models.py # Pydantic v2 input models
│ └── formatters.py # Response extractors and Markdown/JSON renderers
├── requirements.txt
├── .env.example
└── README.mdTroubleshooting
Error | Fix |
| Set |
| Verify the key is valid and PageSpeed Insights API is enabled in your Cloud project |
| Ensure the URL is publicly accessible and starts with |
| Reduce request frequency; the server retries automatically up to 3 times |
| The page may be unreachable or very slow; try again |
| PWA category was removed from Lighthouse 12+ — do not pass |
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Bulk PageSpeed Insights and Core Web Vitals (LCP, INP, CLS) for many URLs. Runs on Apify.
Google PageSpeed Insights (Lighthouse) scores, Core Web Vitals and top speed fixes for every URL...
Google PageSpeed Insights — runs Lighthouse against any public URL and returns the performance…
Lighthouse scores, Core Web Vitals (LCP, CLS, INP/TBT) and top fixes for any URL, mobile or desktop.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceActs as a bridge between AI models and Google's PageSpeed Insights API, enabling detailed performance analysis of websites.13MIT
- AlicenseBqualityDmaintenanceEnables AI models to analyze webpage performance using the Google PageSpeed Insights API, providing real-time performance scores and improvement suggestions.1193 npm12MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to perform comprehensive web performance analysis using Google's PageSpeed Insights API, including metrics, best practices, SEO, and accessibility audits.44 npmMIT
- AlicenseBqualityDmaintenanceEnables web performance analysis using Google PageSpeed Insights and Chrome UX Report APIs, providing compact metrics and diagnostics without local browser automation.56 npmMIT