PageSpeed Insights MCP server

The PageSpeed MCP Server allows AI assistants to analyze website performance by connecting them to Google's PageSpeed Insights API. It provides detailed metrics on performance, accessibility, SEO, and best practices for any given URL.

Installation Options

Installing via Smithery

For automatic installation with Claude Desktop via Smithery:

npx -y @smithery/cli install mcp-pagespeed-server --client claude

Manual Installation

Install using npm:

npm install pagespeed-mcp-server

Configuration

Add the PageSpeed MCP to your AI assistant's configuration file:

{
    "pagespeed": {
        "command": "node",
        "args": ["path/to/mcp-pagespeed-server/dist/index.js"]
    }
}

Capabilities

Performance Metrics Analysis

• First Contentful Paint (FCP)
• Largest Contentful Paint (LCP)
• Time to Interactive (TTI)
• Total Blocking Time (TBT)
• Cumulative Layout Shift (CLS)
• Speed Index
• Time to First Byte (TTFB)

Best Practices Assessment

• HTTPS usage
• JavaScript error monitoring
• Browser console warnings
• Deprecated API usage
• Image aspect ratio analysis
• Link security checks

SEO Analysis

• Meta description validation
• Robots.txt validation
• Structured data validation
• Crawlable links verification
• Meta tags assessment
• Mobile friendliness

Accessibility Audits

• ARIA attribute validation
• Color contrast checking
• Heading hierarchy analysis
• Alt text verification
• Focus management assessment
• Keyboard navigation testing

Resource Optimization

• Image optimization suggestions
• JavaScript bundling analysis
• CSS optimization recommendations
• Cache policy validation
• Resource minification checks
• Render-blocking resource identification

API Response Structure

The server provides detailed JSON responses with this structure:

{
    "lighthouseResult": {
        "categories": {
            "performance": { /* Performance metrics */ },
            "accessibility": { /* Accessibility results */ },
            "best-practices": { /* Best practices audit */ },
            "seo": { /* SEO findings */ }
        },
        "audits": {
            // Detailed audit results for each category
        },
        "timing": {
            // Performance timing data
        },
        "stackPacks": {
            // Technology-specific advice
        }
    }
}

Advanced Usage

Custom Configuration

Customize the PageSpeed analysis with additional parameters:

{
    "strategy": "mobile", // or "desktop"
    "category": ["performance", "accessibility", "best-practices", "seo"],
    "locale": "en",
    "threshold": {
        "performance": 90,
        "accessibility": 100,
        "best-practices": 90,
        "seo": 90
    }
}

Error Handling

The server handles various errors including:

• Invalid URLs
• Network timeouts
• API rate limiting
• Invalid parameters
• Server-side errors

Requirements

Network Requirements

• Stable internet connection
• Access to Google's PageSpeed Insights API

Platform Support

• Windows (x64, x86)
• Linux (x64)
• macOS (x64, arm64)

Integration Examples

Basic Integration

const PageSpeedMCP = require('pagespeed-mcp-server');
const mcp = new PageSpeedMCP();

await mcp.analyze('https://example.com');

With Custom Options

const results = await mcp.analyze('https://example.com', {
    strategy: 'mobile',
    categories: ['performance', 'accessibility'],
    locale: 'en-US'
});

Troubleshooting

Common Issues

1. Connection Timeouts

   • Check internet connectivity

2. API Rate Limiting

   • Use API key for higher limits

3. Memory Issues

   • Adjust Node.js memory limits

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "pagespeed" '{"command":"node","args":["path/to/mcp-pagespeed-server/dist/index.js"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "pagespeed": {
            "command": "node",
            "args": [
                "path/to/mcp-pagespeed-server/dist/index.js"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "pagespeed": {
            "command": "node",
            "args": [
                "path/to/mcp-pagespeed-server/dist/index.js"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect