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

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

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

Manual VS Code Installation

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

Manual Cursor Installation

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

Manual Windsurf Installation

Follow the Windsurf MCP documentation. Use the following configuration:

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

Install in Claude Desktop

Claude Desktop Installation

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://pe