MCP server for Google PageSpeed Insights API - analyze web performance with Claude
npm install pagespeed-insights-mcp
MCP server for Google PageSpeed Insights API that enables web page performance analysis directly through Claude.
bash
Set environment variable
export GOOGLE_API_KEY=your-google-api-key
`bash
curl -sSL https://raw.githubusercontent.com/ruslanlap/pagespeed-insights-mcp/master/install.sh | bash
`$3
#### From npm (Public Registry)
bash
Global installation from npm
npm install -g pagespeed-insights-mcpOr use without installation
npx pagespeed-insights-mcpSpecific version
npm install -g pagespeed-insights-mcp@1.0.6
`#### From GitHub Packages
bash
First configure authentication (see GITHUB_PACKAGES.md for details)
Then install globally
npm install -g @ruslanlap/pagespeed-insights-mcpOr specific version
npm install -g @ruslanlap/pagespeed-insights-mcp@1.0.6
`> Note: This package is available on both npm and GitHub Packages.
> - For npm: Use
> - For GitHub Packages: Use (requires GitHub authentication)
>
> For detailed instructions on installing from GitHub Packages, see GITHUB_PACKAGES.md or visit the GitHub Packages page$3
The MCP server requires a Google API key to access the PageSpeed Insights API.
`bash
Set environment variable
export GOOGLE_API_KEY=your-google-api-keyOr pass directly when running
GOOGLE_API_KEY=your-google-api-key npx pagespeed-insights-mcp
`$3
To use this MCP server with Claude Desktop, add the following to your Claude Desktop configuration file:
json
{
"mcpServers": {
"pagespeed": {
"command": "npx",
"args": ["pagespeed-insights-mcp"],
"env": {
"GOOGLE_API_KEY": "your-google-api-key-here"
}
}
}
}
`Example configuration files are available in the examples directory.
$3
bash
docker build -t pagespeed-insights-mcp .
docker run -e GOOGLE_API_KEY=your-key pagespeed-insights-mcp
`🔑 Getting Google API Key
1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable PageSpeed Insights API:
- Navigate to "APIs & Services" → "Library"
- Search for "PageSpeed Insights API" and enable it
4. Create an API key:
- Go to "APIs & Services" → "Credentials"
- Click "Create Credentials" → "API Key"
- Copy the generated key
⚙️ Claude Desktop Configuration
$3
If you used the install.sh script, the configuration was created automatically.$3
Add the configuration to your Claude Desktop file:
macOS:
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/claude/claude_desktop_config.json#### For npm installation and global installation
json
{
"mcpServers": {
"pagespeed-insights": {
"command": "npx",
"args": ["pagespeed-insights-mcp"],
"env": {
"GOOGLE_API_KEY": "your-google-api-key-here"
}
}
}
}
`#### For GitHub Packages installation
json
{
"mcpServers": {
"pagespeed-insights": {
"command": "npx",
"args": ["@ruslanlap/pagespeed-insights-mcp"],
"env": {
"GOOGLE_API_KEY": "your-google-api-key-here"
}
}
}
}
`
#### For Docker:
json
{
"mcpServers": {
"pagespeed-insights": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"--env", "GOOGLE_API_KEY=your-google-api-key-here",
"pagespeed-insights-mcp"
]
}
}
}
`Restart Claude Desktop after configuration!
💻 Usage
After configuration, simply ask Claude any of these commands:
$3
Analyze the performance of https://example.com
$3
Analyze https://example.com for mobile devices with all categories
$3
Get a quick performance report for https://example.com
$3
Analyze https://example.com performance for desktop devices
$3
Perform a full audit of https://example.com including SEO, accessibility, and best practices
$3
Get smart recommendations for improving https://example.com performance
$3
Clear the cache to get fresh data for all subsequent requests
$3
Get visual analysis for https://example.com showing screenshots and loading timeline
$3
Show me which specific elements are causing performance issues on https://example.com
$3
Analyze the network requests and resource loading for https://example.com
$3
Get JavaScript execution breakdown for https://example.com
$3
Show me which images need optimization on https://example.com
$3
Find render-blocking resources on https://example.com
$3
Analyze third-party script impact on https://example.com performance
$3
Run a full audit including accessibility, SEO, and best practices for https://example.com
Available Tools
$3
Complete page analysis with all Lighthouse metrics.
Parameters:
-
(required): URL of the page to analyze
- strategy: "mobile" or "desktop" (default: "mobile")
- category: array of categories ["performance", "accessibility", "best-practices", "seo", "pwa"]
- locale: locale for results (default: "en")$3
Simplified report with key performance metrics.
$3
Generate smart performance recommendations with priority scoring and actionable fixes.
Parameters:
-
url (required): URL of the page to analyze
- strategy: "mobile" or "desktop" (default: "mobile")
- category: array of categories to analyze (default: ["performance", "accessibility", "best-practices", "seo"])
- locale: locale for results (default: "en")$3
Clear the internal cache to force fresh API requests for all subsequent analyses.
$3
Get screenshots and visual timeline showing how the page loads.
Parameters:
-
url (required): URL of the page to analyze
- strategy: "mobile" or "desktop" (default: "mobile")Returns:
- Final screenshot of the loaded page
- Filmstrip showing page load progression
- Full-page screenshot with DOM node mapping
$3
Get specific DOM elements causing performance issues.
Parameters:
-
url (required): URL of the page to analyze
- strategy: "mobile" or "desktop" (default: "mobile")Returns:
- LCP (Largest Contentful Paint) element details
- CLS (Cumulative Layout Shift) causing elements
- Lazy-loaded LCP warnings
$3
Get detailed network waterfall showing all requests with timing and size.
Parameters:
-
url (required): URL of the page to analyze
- strategy: "mobile" or "desktop" (default: "mobile")Returns:
- All network requests with timing data
- Resource breakdown by type
- Total transfer size and request count
- Network RTT and server latency
$3
Get JavaScript execution breakdown showing performance impact.
Parameters:
-
url (required): URL of the page to analyze
- strategy: "mobile" or "desktop" (default: "mobile")Returns:
- JavaScript bootup time by script
- Main thread work breakdown
- Unused JavaScript analysis
- Duplicated JavaScript modules
$3
Get specific images needing optimization with exact savings potential.
Parameters:
-
url (required): URL of the page to analyze
- strategy: "mobile" or "desktop" (default: "mobile")Returns:
- Improperly sized images
- Offscreen images (lazy-loading candidates)
- Unoptimized images
- Modern format recommendations (WebP/AVIF)
$3
Get render-blocking resources and critical request chains.
Parameters:
-
url (required): URL of the page to analyze
- strategy: "mobile" or "desktop" (default: "mobile")Returns:
- Render-blocking CSS and JavaScript files
- Critical request chains showing dependencies
- Total blocking time
$3
Get third-party script impact analysis grouped by entity.
Parameters:
-
url (required): URL of the page to analyze
- strategy: "mobile" or "desktop" (default: "mobile")Returns:
- Impact by provider (Google, Facebook, etc.)
- Transfer size and blocking time per provider
- Recommended facade replacements
$3
Get comprehensive audit results for all Lighthouse categories.
Parameters:
-
url (required): URL of the page to analyze
- strategy: "mobile" or "desktop" (default: "mobile")
- categories: array of categories to audit (default: ["performance", "accessibility", "best-practices", "seo"])Returns:
- Scores for all categories
- Detailed Core Web Vitals and metrics
- Key failing audits for each category
- Framework-specific advice (if applicable)
$3
answer example from Claude Desktop with pagespeed-insights-mcp 🔥🔥🔥Complete Ratings for example.com
Now I have the full analysis! Here are all the ratings:
$3
| Category | Score | Status |
| --- | --- | --- |
| Performance | 67/100 | 🟡 Needs Improvement |
| Accessibility | 92/100 | 🟢 Good |
| Best Practices | 96/100 | 🟢 Excellent |
| SEO | 100/100 | 🟢 Perfect |
$3
| Metric | Value | Score |
| --- | --- | --- |
| First Contentful Paint | 1.2s | 🟢 Excellent (98/100) |
| Largest Contentful Paint | 2.4s | 🟡 Needs Improvement (75/100) |
| Speed Index | 4.8s | 🟡 Needs Improvement (67/100) |
| Total Blocking Time | 60ms | 🟢 Good (94/100) |
| Cumulative Layout Shift | 0 | 🟢 Perfect (100/100) |
$3
| Audit | Score | Description |
| --- | --- | --- |
| Label Content Name Mismatch | 🔴 0/1 | 2 errors with aria-label |
| Unsized Images | 🟡 0.5/1 | 1 image without dimensions |
| Color Contrast | 🟢 1/1 | Sufficient contrast |
| Button Names | 🟢 1/1 | Accessible button names |
| Link Names | 🟢 1/1 | Accessible link names |
| ARIA Roles | 🟢 1/1 | Correct ARIA roles |
| HTML Lang | 🟢 1/1 | Valid lang attribute |
| Meta Viewport | 🟢 1/1 | Proper viewport |
| Image Alt Text | 🟢 1/1 | Correct alt attributes |
| List Items | 🟢 1/1 | Proper list structure |
$3
| Audit | Score | Status |
| --- | --- | --- |
| Uses HTTPS | 🟢 ✓ | HTTPS is used |
| HTTP Status Code | 🟢 1/1 | Correct 200 status |
| No Console Errors | 🟢 1/1 | No console errors |
| Valid Source Maps | 🟢 1/1 | Valid source maps |
| No Notification Requests | 🟢 1/1 | No notification requests |
| Charset Declaration | 🟢 1/1 | Correct encoding |
| No Inspector Issues | 🟢 1/1 | No DevTools issues |
$3
| Audit | Score | Status |
| --- | --- | --- |
| Meta Viewport | 🟢 1/1 | Mobile optimized |
| Document Title | 🟢 1/1 | Title present |
| Meta Description | 🟢 1/1 | Description present |
| HTTP Status Code | 🟢 1/1 | Successful status |
| Link Text | 🟢 1/1 | Descriptive link texts |
| Crawlability | 🟢 1/1 | Available for indexing |
| HTML Lang | 🟢 1/1 | Valid document language |
| Hreflang | 🟢 1/1 | Correct hreflang attributes |
$3
| Issue | Affects | Potential Savings |
| --- | --- | --- |
| Improperly sized images | LCP, FCP | 1,069 KB, 170ms |
| Inefficient caching | Overall speed | 1,445 KB |
| Forced Reflows | Smoothness | 46.8ms |
| JavaScript execution time | TBT | 338ms |
$3
| Metric | Value |
| --- | --- |
| Server Response Time | 120ms (🟢 Good) |
| Network RTT | Minimal |
| Main Thread Work | 0.9s |
| DOM Size | 453 elements (optimal) |
$3
1. 🔴 High Priority:
- Optimize image sizes (save 1+ MB)
- Fix aria-label mismatches for accessibility
2. 🟡 Medium Priority:
- Improve caching policy (TTL >600s)
- Add width/height attributes for images
3. 🟢 Low Priority:
- Optimize forced reflows in JavaScript
$3
Overall Rating: Good with potential for improvement
- SEO: Perfect (100/100) 🏆
- Best Practices: Excellent (96/100) 🏆
- Accessibility: Good (92/100) ✅
- Performance: Needs attention (67/100) ⚠️
The site has excellent SEO optimization and follows best practices, but needs image optimization to improve performance.
Parameters:
-
url (required): URL of the page to analyze
- strategy: "mobile" or "desktop" (default: "mobile")Development
`bash
Development mode
npm run devBuild project
npm run buildRun built server
npm start
`Troubleshooting
$3
Ensure the Special thanks to @engmsaleh (Mohamed Saleh Zaied) for his significant contribution to the development of this project.
MIT
For bug reports or feature requests, please create an issue in the repository.