Lighthouse MCP Server

A Model Context Protocol (MCP) server that provides comprehensive web performance auditing and analysis capabilities using Google Lighthouse. This server enables LLMs and AI agents to perform detailed website performance assessments, accessibility audits, SEO analysis, security checks, and Core Web Vitals monitoring.

🌟 Key Features

• 🚀 Performance Analysis: Complete Lighthouse audits with Core Web Vitals, performance scores, and optimization recommendations
• ♿ Accessibility Audits: WCAG compliance checking and accessibility score analysis
• 🔍 SEO Analysis: Search engine optimization audits and best practice recommendations
• 🔒 Security Assessment: HTTPS, CSP, and security vulnerability scanning
• 📊 Resource Analysis: JavaScript, CSS, image, and font optimization opportunities
• 📱 Mobile vs Desktop: Comparative analysis across devices with throttling options
• ⚡ Core Web Vitals: LCP, INP, CLS monitoring with threshold checking
• 🎯 Performance Budgets: Custom performance thresholds and budget monitoring
• 🤖 Agentic Browsing: Lighthouse 13 audits for how well a page serves AI agents (WebMCP tools, agent accessibility tree, llms.txt)
• 🧩 Structured Output: Every tool declares an outputSchema and returns validated structuredContent, so clients get typed data instead of a JSON string to parse
• 📚 Reference Resources: Built-in guidelines and best practices for web performance, accessibility, SEO, and security

🛠️ Requirements

• Node.js 22.0.0 or newer
• Chrome/Chromium browser (automatically managed by Lighthouse)
• VS Code, Cursor, Windsurf, Claude Desktop, or any other MCP client

🚀 Getting Started

Install the Lighthouse MCP server with your preferred client using one of the configurations below:

{
  "mcpServers": {
    "lighthouse": {
      "command": "npx",
      "args": ["@danielsogl/lighthouse-mcp@latest"]
    }
  }
}

Persistent Chrome Profiles (Login Sessions)

If you need authenticated sessions, launch with a persistent Chrome profile and run headed:

{
  "mcpServers": {
    "lighthouse": {
      "command": "npx",
      "args": [
        "@danielsogl/lighthouse-mcp@latest",
        "--profile-path",
        "<profile-path>",
        "--no-headless"
      ]
    }
  }
}

You can pass extra Chrome flags with --chrome-flag, for example --chrome-flag=--disable-gpu. If the flag value starts with -- and matches a known option name, prefer --chrome-flag=... to avoid parsing it as a top-level option. Profile mode disables Lighthouse's storage reset so cookies and local storage persist between runs. If --user-data-dir points to a missing directory, it will be created and treated as a fresh profile. Set --profile-path to the Profile Path shown in chrome://version (e.g. .../Default). Note: Chrome's remote debugging requires a non-default user data directory, so reuse a dedicated profile directory instead of the system default. You can also pass --user-data-dir + --profile-directory separately if you prefer. Attaching with --chrome-port alone does not preserve storage; include a profile flag to keep sessions.

CLI Options

Supported runtime flags for the MCP server:

• --profile-path <path>: use the Profile Path from chrome://version (auto-derives user data dir + profile name)
• --user-data-dir <path>: reuse a Chrome profile directory for persistent sessions
• --profile-directory <name>: select a profile within the user data dir
• --chrome-path <path>: explicit path to the Chrome/Chromium executable (overrides auto-detection; also respects the CHROME_PATH environment variable)
• --chrome-flag <flag> or --chrome-flag=<flag>: pass through extra Chrome flags (repeatable)
• --chrome-port <port> or --remote-debugging-port <port>: attach to an existing Chrome instance launched with remote debugging enabled
• --headless: force headless mode
• --no-headless: force headed mode

Logging

Lighthouse logs to stderr. The server keeps this at error so it does not flood your MCP client's logs; set LIGHTHOUSE_LOG_LEVEL to silent, info or verbose when debugging (for example when Chrome fails to launch).

LIGHTHOUSE_LOG_LEVEL=verbose npx @danielsogl/lighthouse-mcp@latest

WSL2 / Custom Chrome Path

If the wrong Chrome binary is picked up (e.g. Windows Chrome instead of the Linux binary on WSL2), set the path explicitly:

# Via CLI flag
npx @danielsogl/lighthouse-mcp@latest --chrome-path /usr/bin/google-chrome

# Via environment variable
CHROME_PATH=/usr/bin/google-chrome npx @danielsogl/lighthouse-mcp@latest

In your MCP config:

{
  "mcpServers": {
    "lighthouse": {
      "command": "npx",
      "args": ["@danielsogl/lighthouse-mcp@latest", "--chrome-path", "/usr/bin/google-chrome"]
    }
  }
}

E2E Smoke Test (Profile)

Run a real audit with a persistent profile (use an existing profile directory and log in once if needed):

npm run smoke:profile -- --url https://example.com \
  --profile-path "<profile-path>" \
  --no-headless

E2E Smoke Test (Attach to Existing Chrome)

Start Chrome with remote debugging enabled:

/path/to/GoogleChromeExecutable \
  --remote-debugging-port=9222 \
  --user-data-dir /path/to/chrome-profile

Replace /path/to/GoogleChromeExecutable with your platform's Chrome/Chromium binary path.

Then attach Lighthouse to that instance:

npm run smoke:profile -- --url https://example.com --chrome-port 9222

To preserve storage when attaching, pass the profile path so Lighthouse keeps cookies/local storage:

npm run smoke:profile -- --url https://example.com \
  --chrome-port 9222 \
  --profile-path "<profile-path>"

Install in VS Code

# For VS Code
code --add-mcp '{"name":"lighthouse","command":"npx","args":["-y","@danielsogl/lighthouse-mcp@latest"]}'

# For VS Code Insiders
code-insiders --add-mcp '{"name":"lighthouse","command":"npx","args":["-y","@danielsogl/lighthouse-mcp@latest"]}'

Install in Cursor

{
  "mcpServers": {
    "lighthouse": {
      "command": "npx",
      "args": ["@danielsogl/lighthouse-mcp@latest"]
    }
  }
}

Install in Windsurf

{
  "mcpServers": {
    "lighthouse": {
      "command": "npx",
      "args": ["@danielsogl/lighthouse-mcp@latest"]
    }
  }
}

Install in Claude Desktop

{
  "mcpServers": {
    "lighthouse": {
      "command": "npx",
      "args": ["@danielsogl/lighthouse-mcp@latest"]
    }
  }
}

🔧 Available Tools

The Lighthouse MCP server provides the following tools for comprehensive web analysis:

🏁 Audit Tools

⚡ Performance Tools

🔍 Analysis Tools

🔒 Security Tools

💬 Available Prompts

The Lighthouse MCP server includes reusable prompts that help LLMs provide structured analysis and recommendations:

📊 Analysis Prompts

📚 Available Resources

The Lighthouse MCP server provides built-in reference resources with essential guidelines and best practices:

🎯 Strategy Prompts

🔧 Prompt Parameter Details

• auditResults: JSON audit results from Lighthouse tools
• focusArea: Specific category to focus on ("performance", "accessibility", "seo", "best-practices", "agentic-browsing")
• beforeAudit / afterAudit: Lighthouse audit results before and after changes
• changesImplemented: Description of changes made between audits
• currentMetrics: Current performance metrics from audits
• targetGoals: Specific performance targets or business goals
• timeframe: Timeline for implementing improvements
• framework: Frontend framework or technology stack
• constraints: Technical or business constraints
• websiteType: Type of website (e.g., e-commerce, blog, corporate)
• targetAudience: Target audience or market information
• complianceLevel: WCAG compliance level ("AA" or "AAA")
• userGroups: Specific user groups to consider for accessibility

📋 Parameter Details

Common Parameters

• url (required): The website URL to analyze
• device: Target device ("desktop" or "mobile", default: "desktop")
• includeDetails: Include detailed audit information (default: false)
• throttling: Enable network/CPU throttling (default: false)

Specific Parameters

• categories: Lighthouse categories to audit (["performance", "accessibility", "best-practices", "seo", "agentic-browsing"])
• threshold: Custom thresholds for metrics (e.g., {"lcp": 2.5, "inp": 200, "cls": 0.1})
• budget: Performance budget limits (e.g., {"performanceScore": 90, "largestContentfulPaint": 2500})
• resourceTypes: Resource types to analyze (["images", "javascript", "css", "fonts", "other"])
• minBytes: Minimum file size threshold for analysis (default: 2048)
• checks: Security checks to perform (["https", "csp", "hsts", "origin-isolation", "clickjacking", "trusted-types", "third-party-cookies", "deprecations"])

💡 Usage Examples

Basic Performance Audit

// Get overall performance score
{
  "tool": "get_performance_score",
  "arguments": {
    "url": "https://example.com",
    "device": "mobile"
  }
}

Core Web Vitals Analysis

// Check Core Web Vitals with custom thresholds
{
  "tool": "get_core_web_vitals",
  "arguments": {
    "url": "https://example.com",
    "device": "mobile",
    "includeDetails": true,
    "threshold": {
      "lcp": 2.5,
      "inp": 200,
      "cls": 0.1
    }
  }
}

Security Assessment

// Comprehensive security audit
{
  "tool": "get_security_audit",
  "arguments": {
    "url": "https://example.com",
    "checks": ["https", "csp", "hsts"]
  }
}

Resource Optimization

// Find optimization opportunities
{
  "tool": "analyze_resources",
  "arguments": {
    "url": "https://example.com",
    "resourceTypes": ["images", "javascript"],
    "minSize": 1024
  }
}

Using Reference Resources

Access built-in guidelines and best practices:

// Get Core Web Vitals thresholds
{
  "resource": {
    "uri": "lighthouse://performance/core-web-vitals-thresholds"
  }
}

// Access WCAG accessibility guidelines
{
  "resource": {
    "uri": "lighthouse://accessibility/wcag-guidelines"
  }
}

// Get framework-specific optimization guides
{
  "resource": {
    "uri": "lighthouse://frameworks/optimization-guides"
  }
}

Using Prompts for Analysis

// Analyze audit results with focused recommendations
{
  "prompt": "analyze-audit-results",
  "arguments": {
    "auditResults": "{...lighthouse audit json...}",
    "focusArea": "performance"
  }
}

// Create a performance improvement plan
{
  "prompt": "create-performance-plan",
  "arguments": {
    "currentMetrics": "{...current performance metrics...}",
    "targetGoals": "Achieve 90+ performance score and sub-2s LCP",
    "timeframe": "3 months"
  }
}

// Compare before/after audit results
{
  "prompt": "compare-audits",
  "arguments": {
    "beforeAudit": "{...before audit results...}",
    "afterAudit": "{...after audit results...}",
    "changesImplemented": "Implemented lazy loading and image optimization"
  }
}

🎯 Use Cases

• Performance Monitoring: Automated performance tracking and Core Web Vitals monitoring
• Accessibility Compliance: WCAG 2.1 compliance checking and remediation guidance
• SEO Optimization: Technical SEO audits and search engine optimization recommendations
• Security Assessment: Vulnerability scanning and security best practice validation
• Resource Optimization: Bundle analysis and optimization opportunity identification
• Performance Budgets: Automated performance budget monitoring and alerting
• CI/CD Integration: Automated quality gates and performance regression detection

🏗️ Architecture

The server is built using:

• Model Context Protocol SDK: For MCP server implementation
• Google Lighthouse: For web performance auditing
• Chrome Launcher: For browser automation
• TypeScript: For type safety and better developer experience
• Zod: For runtime schema validation

🧪 Testing

npm run test:run      # unit tests
npm run test:coverage # unit tests with coverage
npm run test:e2e      # end-to-end tests

The end-to-end suite builds the server, launches it over stdio with a real MCP client, and runs actual Lighthouse audits against a fixture page served on loopback. It requires Chrome to be installed; set CHROME_PATH if it lives somewhere non-standard.

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details on:

• Code style and standards
• Testing requirements
• Pull request process
• Development setup

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔒 Security

For security issues, please see our Security Policy.

📞 Support

• 🐛 Bug Reports: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Email: [email protected]

🙏 Acknowledgments

• Google Lighthouse team for the excellent auditing engine
• Anthropic for the Model Context Protocol specification
• The open source community for continuous inspiration and contributions

Built with ❤️ by Daniel Sogl