Lighthouse MCP

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, FID, CLS monitoring with threshold checking
🎯 Performance Budgets: Custom performance thresholds and budget monitoring
📚 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"]
    }
  }
}

Install in VS Code

You can also install the Lighthouse MCP server using the VS Code CLI:

# 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"]}'

After installation, the Lighthouse MCP server will be available for use with your GitHub Copilot agent in VS Code.

Install in Cursor

Go to Cursor Settings → MCP → Add new MCP Server. Name it "lighthouse", use command type with the command npx @danielsogl/lighthouse-mcp@latest:

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

Install in Windsurf

Follow the Windsurf MCP documentation. Use the following configuration:

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

Install in Claude Desktop

Follow the MCP install guide, use the following configuration:

{
  "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

Tool	Description	Parameters
`run_audit`	Run a comprehensive Lighthouse audit	`url`, `categories?`, `device?`, `throttling?`
`get_accessibility_score`	Get accessibility score and recommendations	`url`, `device?`, `includeDetails?`
`get_seo_analysis`	Get SEO analysis and recommendations	`url`, `device?`, `includeDetails?`
`check_pwa_readiness`	Check Progressive Web App readiness	`url`, `device?`, `includeDetails?`

⚡ Performance Tools

Tool	Description	Parameters
`get_performance_score`	Get overall performance score	`url`, `device?`
`get_core_web_vitals`	Get Core Web Vitals metrics	`url`, `device?`, `includeDetails?`, `threshold?`
`compare_mobile_desktop`	Compare performance across devices	`url`, `categories?`, `throttling?`, `includeDetails?`
`check_performance_budget`	Check against performance budgets	`url`, `device?`, `budget`
`get_lcp_opportunities`	Find LCP optimization opportunities	`url`, `device?`, `includeDetails?`, `threshold?`

🔍 Analysis Tools

Tool	Description	Parameters
`find_unused_javascript`	Find unused JavaScript code	`url`, `device?`, `minBytes?`, `includeSourceMaps?`
`analyze_resources`	Analyze all website resources	`url`, `device?`, `resourceTypes?`, `minSize?`

🔒 Security Tools

Tool	Description	Parameters
`get_security_audit`	Perform comprehensive security audit	`url`, `device?`, `checks?`

💬 Available Prompts

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

📊 Analysis Prompts

Prompt	Description	Parameters
`analyze-audit-results`	Analyze Lighthouse audit results	`auditResults`, `focusArea?`
`compare-audits`	Compare before/after audit results	`beforeAudit`, `afterAudit`, `changesImplemented?`
`optimize-core-web-vitals`	Get Core Web Vitals optimization recommendations	`coreWebVitals`, `framework?`, `constraints?`
`optimize-resources`	Get resource optimization recommendations	`resourceAnalysis`, `loadingStrategy?`, `criticalUserJourneys?`

📚 Available Resources

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

Resource	Description	URI
`core-web-vitals-thresholds`	Core Web Vitals performance thresholds	`lighthouse://performance/core-web-vitals-thresholds`
`optimization-techniques`	Performance optimization techniques and impact	`lighthouse://performance/optimization-techniques`
`wcag-guidelines`	WCAG 2.1 accessibility guidelines and issues	`lighthouse://accessibility/wcag-guidelines`
`seo-best-practices`	SEO best practices and optimization opportunities	`lighthouse://seo/best-practices`
`security-best-practices`	Web security best practices and vulnerabilities	`lighthouse://security/best-practices`
`budget-guidelines`	Performance budget recommendations by site type	`lighthouse://performance/budget-guidelines`
`categories-scoring`	Lighthouse audit categories and scoring methods	`lighthouse://audits/categories-scoring`
`framework-guides`	Framework-specific optimization guides	`lighthouse://frameworks/optimization-guides`

🎯 Strategy Prompts

Prompt	Description	Parameters
`create-performance-plan`	Generate comprehensive performance improvement plan	`currentMetrics`, `targetGoals?`, `timeframe?`
`create-performance-budget`	Create custom performance budget recommendations	`currentMetrics`, `businessGoals?`, `userBase?`
`seo-recommendations`	Generate SEO improvement recommendations	`seoAudit`, `websiteType?`, `targetAudience?`
`accessibility-guide`	Create accessibility improvement guide	`accessibilityAudit`, `complianceLevel?`, `userGroups?`

🔧 Prompt Parameter Details

auditResults: JSON audit results from Lighthouse tools
focusArea: Specific category to focus on ("performance", "accessibility", "seo", "best-practices", "pwa")
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", "pwa"])
threshold: Custom thresholds for metrics (e.g., {"lcp": 2.5, "fid": 100, "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", "mixed-content", "csp", "hsts", "vulnerabilities"])

💡 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,
      "fid": 100,
      "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

🤝 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: security@codingrules.ai

🙏 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

Install Server

HTTP connection URL

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Tools

View all tools