Lighthouse MCP Server

Lighthouse MCP 服务

一个使用 Google Lighthouse 提供全面 Web 性能审计和分析能力的模型上下文协议（MCP）服务。此服务可让大模型和 AI Agent 执行详细的网站性能评估、无障碍审计、SEO 分析、安全检查和 Core Web Vitals 监控。

🌟 主要功能

• 🚀 性能分析：完整的 Lighthouse 审计，涵盖 Core Web Vitals、性能评分和优化建议
• ♿ 无障碍审计：WCAG 合规性检查和无障碍评分分析
• 🔍 SEO 分析：搜索引擎优化审计和最佳实践建议
• 🔒 安全评估：HTTPS、CSP 和安全漏洞扫描
• 📊 资源分析：JavaScript、CSS、图像和字体优化机会
• 📱 移动端与桌面端对比：跨设备对比分析，并支持限速选项
• ⚡ Core Web Vitals：监控 LCP、INP、CLS，并检查阈值
• 🎯 性能预算：自定义性能阈值和预算监控
• 🤖 Agent 式浏览：Lighthouse 13 审计页面为 AI Agent 提供服务的能力（WebMCP 工具、Agent 无障碍树、llms.txt）
• 🧩 结构化输出：每个工具都声明 outputSchema 并返回经过验证的 structuredContent，因此客户端可获取类型化数据，而无需解析 JSON 字符串
• 📚 参考资源：内置 Web 性能、无障碍、SEO 和安全指南及最佳实践

🛠️ 要求

• Node.js 22.0.0 或更高版本
• Chrome/Chromium 浏览器（由 Lighthouse 自动管理）
• VS Code、Cursor、Windsurf、Claude Desktop 或任何其他 MCP 客户端

🚀 开始使用

使用以下任一配置，通过你偏好的客户端安装 Lighthouse MCP 服务：

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

持久化 Chrome 配置文件（登录会话）

如需使用已验证身份的会话，请使用持久化 Chrome 配置文件启动，并以有界面模式运行：

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

你可以通过 --chrome-flag 传递额外的 Chrome 标志，例如 --chrome-flag=--disable-gpu。 如果标志值以 -- 开头且与已知选项名称匹配，建议使用 --chrome-flag=...，以免被解析为顶层选项。 配置文件模式会禁用 Lighthouse 的存储重置，因此 Cookie 和本地存储会在运行之间保留。 如果 --user-data-dir 指向不存在的目录，该目录将被创建并视为全新配置文件。 将 --profile-path 设置为 chrome://version 中显示的 Profile Path（例如 .../Default）。 注意：Chrome 的远程调试要求使用非默认用户数据目录，因此请使用专用配置文件目录，而不要使用系统默认目录。 你也可以根据需要分别传递 --user-data-dir 和 --profile-directory。 仅使用 --chrome-port 连接不会保留存储；要保留会话，请同时指定配置文件标志。

CLI 选项

MCP 服务支持的运行时标志：

• --profile-path <path>：使用 chrome://version 中的 Profile Path（自动推导用户数据目录和配置文件名称）
• --user-data-dir <path>：复用 Chrome 配置文件目录，以用于持久会话
• --profile-directory <name>：在用户数据目录中选择一个配置文件
• --chrome-path <path>：显式指定 Chrome/Chromium 可执行文件的路径（覆盖自动检测；也会读取 CHROME_PATH 环境变量）
• --chrome-flag <flag> 或 --chrome-flag=<flag>：传递额外的 Chrome 标志（可重复使用）
• --chrome-port <port> 或 --remote-debugging-port <port>：连接到已启用远程调试启动的 Chrome 实例
• --headless：强制使用无头模式
• --no-headless：强制使用有头模式

日志记录

Lighthouse 将日志输出到 stderr。服务将日志级别设为 error，以免 MCP 客户端的日志被刷屏；调试时（例如 Chrome 启动失败时），可将 LIGHTHOUSE_LOG_LEVEL 设为 silent、info 或 verbose。

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

WSL2 / 自定义 Chrome 路径

如果选中了错误的 Chrome 二进制文件（例如在 WSL2 上选中了 Windows 版 Chrome，而不是 Linux 二进制文件），请显式设置路径：

# 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

在 MCP 配置中：

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

E2E 冒烟测试（配置文件）

使用持久配置文件运行实际审计（使用现有配置文件目录，并在需要时登录一次）：

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

E2E 冒烟测试（连接到现有 Chrome）

启动已启用远程调试的 Chrome：

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

将 /path/to/GoogleChromeExecutable 替换为适用于你平台的 Chrome/Chromium 二进制文件路径。

然后将 Lighthouse 连接到该实例：

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

连接时若要保留存储，请传入配置文件路径，以便 Lighthouse 保留 Cookie/本地存储：

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

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

在 Cursor 中安装

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

在 Windsurf 中安装

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

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

🔧 可用工具

Lighthouse MCP 服务提供以下工具，助你全面分析网站：

🏁 审计工具

⚡ 性能工具

🔍 分析工具

🔒 安全工具

💬 可用提示词

Lighthouse MCP 服务包含可复用的提示词，可帮助大模型提供结构化分析和建议：

📊 分析提示词

📚 可用资源

Lighthouse MCP 服务提供内置的参考资源，包含重要指南和最佳实践：

🎯 策略提示词

🔧 提示词参数详情

• auditResults：来自 Lighthouse 工具的 JSON 审计结果
• focusArea：要重点关注的特定类别（"performance"、"accessibility"、"seo"、"best-practices"、"agentic-browsing"）
• beforeAudit / afterAudit：更改前后的 Lighthouse 审计结果
• changesImplemented：审计之间所做更改的说明
• currentMetrics：审计中的当前性能指标
• targetGoals：具体性能目标或业务目标
• timeframe：实施改进的时间安排
• framework：前端框架或技术栈
• constraints：技术或业务限制
• websiteType：网站类型（例如，电商、博客、企业网站）
• targetAudience：目标受众或市场信息
• complianceLevel：WCAG 合规级别（"AA" 或 "AAA"）
• userGroups：无障碍设计需要考虑的特定用户群体

📋 参数详情

常用参数

• url（必填）：要分析的网站 URL
• device：目标设备（"desktop" 或 "mobile"，默认值："desktop"）
• includeDetails：包含详细的审计信息（默认值：false）
• throttling：启用网络/CPU 限速（默认值：false）

特定参数

• categories：要审核的 Lighthouse 类别（["performance", "accessibility", "best-practices", "seo", "agentic-browsing"]）
• threshold：指标的自定义阈值（例如，{"lcp": 2.5, "inp": 200, "cls": 0.1}）
• budget：性能预算限制（例如，{"performanceScore": 90, "largestContentfulPaint": 2500}）
• resourceTypes：要分析的资源类型（["images", "javascript", "css", "fonts", "other"]）
• minBytes：分析所需的最小文件大小阈值（默认值：2048）
• checks：要执行的安全检查（["https", "csp", "hsts", "origin-isolation", "clickjacking", "trusted-types", "third-party-cookies", "deprecations"]）

💡 使用示例

基本性能审核

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

Core Web Vitals 分析

// 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
    }
  }
}

安全评估

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

资源优化

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

使用参考资源

访问内置指南和最佳实践：

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

使用提示词进行分析

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

🎯 使用场景

• 性能监控：自动跟踪性能并监控 Core Web Vitals
• 无障碍合规：检查 WCAG 2.1 合规性并提供修复指导
• SEO 优化：技术 SEO 审核和搜索引擎优化建议
• 安全评估：漏洞扫描和安全最佳实践验证
• 资源优化：分析打包文件并识别优化机会
• 性能预算：自动监控性能预算并发出警报
• CI/CD 集成：自动质量门禁和性能回归检测

🏗️ 架构

该服务使用以下技术构建：

• Model Context Protocol SDK：用于实现 MCP 服务
• Google Lighthouse：用于审核 Web 性能
• Chrome Launcher：用于浏览器自动化
• TypeScript：用于确保类型安全并提升开发者体验
• Zod：用于运行时模式验证

🧪 测试

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

端到端测试套件会构建服务，通过 stdio 使用真实的 MCP 客户端启动服务，并针对通过 loopback 提供的测试页面运行实际的 Lighthouse 审核。测试需要安装 Chrome；如果 Chrome 位于非标准路径，请设置 CHROME_PATH。

🤝 参与贡献

欢迎贡献！请阅读我们的贡献指南，了解以下详情：

• 代码风格和标准
• 测试要求
• Pull request 流程
• 开发环境设置

📜 许可证

本项目采用 MIT 许可证授权——详情请参阅 LICENSE 文件。

🔒 安全

有关安全问题，请参阅我们的安全政策。

📞 支持

• 🐛 错误报告：GitHub Issues
• 💬 讨论：GitHub Discussions
• 📧 电子邮件：[email protected]

🙏 致谢

• 感谢 Google Lighthouse 团队打造了出色的审核引擎
• 感谢 Anthropic 制定 Model Context Protocol 规范
• 感谢开源社区持续提供灵感并贡献力量

由 Daniel Sogl 倾情打造 ❤️