READMEmain

Lighthouse MCP Server

Name: lighthouse-mcp
Author: priyankark

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"
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 22.19+
Chrome/Chromium browser (for Lighthouse)

Endorsements

Security

Chrome runs with its sandbox enabled. Localhost, IPv4 loopback, and IPv6 loopback remain supported by default. Private, link-local, cloud metadata, and other non-public destinations are blocked, including requests made by redirects and page resources. Connections use validated IP addresses to prevent DNS rebinding. Because loopback access is intentional, audit only pages you trust to access services on your own machine. For hostile sites, use a separate environment with network isolation.

Audits are limited to one at a time and time out after 120 seconds. Chrome and the audit proxy are cleaned up after success or failure.

Public-only audits

Set AUDIT_ALLOW_LOOPBACK=false to reject loopback destinations as well as private and metadata addresses. Hosted workers must use this setting and infrastructure egress isolation. Local development keeps loopback access by default.

Maintainer CI and releases

GitHub Actions runs the build, network and release-policy tests, npm security audit, and real Chrome smoke tests on the minimum supported Node version and Node 24. Node 24 also installs the npm tarball in a clean temporary project and checks its executable, dependencies, MCP version, and browser audits.

Every push to main runs the release pipeline. When package files change, it automatically increments the patch version (or honors a larger version already committed), synchronizes package metadata, repeats validation, commits and tags the release, publishes to npm with provenance, and creates a GitHub release. Changes limited to documentation, tests, or workflows do not publish a new version. Runtime server versions come from package.json.

Dependabot checks npm and GitHub Actions weekly. A successful PR CI run automatically merges npm updates only when all existing changed dependencies are stable patch/minor upgrades and only package.json / package-lock.json changed. Major upgrades, 0.x minor upgrades, downgrades, prereleases, and GitHub Actions changes require review. The merge job runs only trusted code from main, verifies the tested PR head, and explicitly dispatches publishing after a bot merge.

npm publishing uses the npm GitHub environment and an npm trusted publisher for priyankark/lighthouse-mcp, workflow publish.yml, environment npm, with direct publishing allowed. No npm token is stored in GitHub. The environment accepts deployments only from main.

To retry a failed release, rerun the Publish workflow or run ./release.sh. The pipeline reuses an unpublished version and skips an already published, unchanged package. If a reserved release tag points to different code, it stops rather than overwriting that version. For a breaking change, update package.json and package-lock.json to the intended major/minor version in the reviewed PR before merging.

lighthouse-mcp