lighthouse-mcp

Lighthouse MCP Server

An MCP server that wraps around Google's Lighthouse tool to help measure various performance metrics for web pages.

Features

• Run comprehensive Lighthouse audits on any URL
• Get performance scores and metrics
• Configure device emulation (mobile/desktop)
• Control network throttling
• Select specific audit categories

Installation

Option 1: From MCP Registry (Recommended)

This server is available in the Model Context Protocol Registry. Install it using your MCP client or Claude Desktop.

Option 2: Using npx

You can run the tool directly using npx without installation:

npx lighthouse-mcp

Option 3: Global Installation

Install the package globally from npm:

npm install -g lighthouse-mcp

Then run it:

lighthouse-mcp

Option 4: Local Development

• Clone this repository
• Install dependencies:

  npm install
  

• Build the project:

  npm run build
  

• Run the server:

  npm start
  

MCP Configuration

When installed via npm (global or npx)

Add the following to your MCP settings configuration file:

{
  "mcpServers": {
    "lighthouse": {
      "command": "npx",
      "args": ["lighthouse-mcp"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

When using local development version

Add the following to your MCP settings configuration file:

{
  "mcpServers": {
    "lighthouse": {
      "command": "node",
      "args": ["/absolute/path/to/lighthouse-mcp/build/index.js"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

Replace /absolute/path/to/lighthouse-mcp with the actual path to this project.

Available Tools

run_audit

Run a comprehensive Lighthouse audit on a URL.

Parameters:

• url (required): The URL to audit
• categories (optional): Array of categories to audit (defaults to all)
  • Options: "performance", "accessibility", "best-practices", "seo", "pwa"
• device (optional): Device to emulate (defaults to "mobile")
  • Options: "mobile", "desktop"
• throttling (optional): Whether to apply network throttling (defaults to true)

Example:

{
  "url": "https://example.com",
  "categories": ["performance", "accessibility"],
  "device": "desktop",
  "throttling": false
}

get_performance_score

Get just the performance score for a URL.

Parameters:

• url (required): The URL to audit
• device (optional): Device to emulate (defaults to "mobile")
  • Options: "mobile", "desktop"

Example:

{
  "url": "https://example.com",
  "device": "mobile"
}

Example Usage

Once the MCP server is configured, you can use it with Claude:

What's the performance score for example.com?

Claude will use the get_performance_score tool to analyze the website and return the results.

Requirements

• Node.js 16+
• Chrome/Chromium browser (for Lighthouse)

Development & Release

Prerequisites

Before releasing, ensure you're authenticated with both registries:

NPM Authentication:

npm login

MCP Registry Authentication:

mcp-publisher login github

If your authentication tokens expire, you'll need to re-login to the respective services.

Making Releases

Use the interactive release script to publish to both NPM and the MCP Registry:

./release.sh

The script will:

• Check NPM login status
• Check for uncommitted changes
• Run tests (if they exist)
• Build the project
• Prompt for version bump type (patch/minor/major/custom)
• Update both package.json and server.json versions
• Create a preview of the package contents
• Publish to NPM
• Publish to MCP Registry (if mcp-publisher is available)
• Create git commit and tag
• Optionally push to remote repository

This ensures consistent releases to both registries with proper version synchronization.