pagespeed-insights-mcp

PageSpeed Insights MCP 服务

面向 Google PageSpeed Insights 和 Chrome UX Report API 的六工具 MCP 服务。可通过 Claude、Cursor 或任何兼容 MCP 的 AI 客户端，直接分析、比较和优化 Web 性能。

⚡ 快速开始（复制并粘贴）

{
  "mcpServers": {
    "pagespeed-insights": {
      "command": "npx",
      "args": ["-y", "pagespeed-insights-mcp"],
      "env": { "GOOGLE_API_KEY": "your-google-api-key" }
    }
  }
}

在 Google Cloud Console 免费获取 API 密钥 → 将其粘贴到 Claude Desktop 的 claude_desktop_config.json 中 → 重启。完成。（Codex/OpenAI 配置，Docker）

🔥 与众不同之处

大多数 PageSpeed MCP 服务只封装一个工具：“对 URL 运行 PSI”。本服务提供六种工作流工具，覆盖完整的性能优化流程——不仅给出分数，还会提供行动计划：

• 完整工具集：页面分析、CrUX 真实用户数据（URL + 来源）、Lighthouse 审计、多页面与批量比较、基线和回归跟踪
• 深度诊断：元素级、网络、JavaScript、图像优化、阻塞渲染及第三方影响分析
• 可执行的输出：建议引擎可将原始 Lighthouse 数据转化为按优先级排列的修复项，并对屏幕截图进行视觉分析
• 实用功能：为重复运行提供缓存，并提供针对 AI Agent 行动优化的智能建议
• 经过实战检验：已发布到 npm，已收录于 Official MCP Registry 和 Glama，并使用 Vitest 进行 CI 测试

🎬 查看交互式演示 → — 通过动画示例查看工具的实际运行效果 备用 URL：https://ruslanlap.github.io/pagespeed-insights-mcp/demo.html

📖 目录

• ⚡ 快速开始（复制并粘贴）
• 🔥 与众不同之处
• ⚙️ 客户端配置
• 📊 示例输出
• 📚 文档
• 📝 发布说明
• 🎯 为什么需要它
• ✨ 功能
• 🚀 快速安装
• 🔑 获取 Google API 密钥
• ⚙️ Claude Desktop 配置
• 💻 使用方法
• 可用工具
• MCP 提示词（斜杠命令）
• MCP 资源
• ✨ 丰富的视觉效果与美观输出
• 开发
• 故障排除
• 要求
• 安全
• 致谢
• 许可证
• 支持

⚙️ 客户端配置

Claude Desktop

将以下内容添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "pagespeed-insights": {
      "command": "npx",
      "args": ["-y", "-p", "pino-pretty", "-p", "pagespeed-insights-mcp", "pagespeed-insights-mcp"],
      "env": {
        "GOOGLE_API_KEY": "your-google-api-key-here"
      }
    }
  }
}

Codex / OpenAI

将以下内容添加到你的配置中（TOML）：

[mcp_servers.pagespeed-insights]
command = "npx"
args = [
  "-y",
  "-p",
  "pino-pretty",
  "-p",
  "pagespeed-insights-mcp",
  "pagespeed-insights-mcp"
]
env = { GOOGLE_API_KEY = "your-google-api-key-here" }

注意： 正确格式化日志需要 pino-pretty 包。上述配置会通过 npx 自动安装该包。

Grok Build 配置（config.toml）

添加到 ~/.grok/config.toml（全局配置）或 <repo>/.grok/config.toml（项目级配置，优先级更高）：

[mcp_servers.pagespeed-insights]
command = "npx"
args = ["-y", "-p", "pino-pretty", "-p", "pagespeed-insights-mcp", "pagespeed-insights-mcp"]
env = { GOOGLE_API_KEY = "${GOOGLE_API_KEY}" }
enabled = true

# Recommended companion professional MCPs (add once):
# [mcp_servers.github]      — PRs, issues, code search
# [mcp_servers.context7]    — fresh library docs (Upstash)
# [mcp_servers.serena]      — semantic code intelligence (uses your .serena/ if present)

项目级配置示例（将其放入此仓库的 .grok/config.toml，以便使用本地 dist/index.js 并采用更严格的 Serena 配置）：

[mcp_servers.pagespeed-insights]
command = "node"
args = ["/home/ubuntuvm/Projects/pagespeed-insights-mcp/dist/index.js"]
env = { GOOGLE_API_KEY = "${GOOGLE_API_KEY}", NODE_ENV = "development" }

在 Grok 会话中验证：

• /mcps（或 Ctrl+L → MCP 选项卡）→ 确认 pagespeed-insights 显示“running”
• 使用工具：pagespeed-insights__pagespeed_analyze_page、pagespeed-insights__pagespeed_get_field_data 等（带命名空间）

📊 示例输出

github.com 的 pagespeed_analyze_page 真实结果——一次移动设备 Lighthouse 运行。CrUX 数据来自 pagespeed_get_field_data，并使用 scope: "origin"：

Lighthouse 实验室评分：

类别	评分	状态
性能（移动设备）	54/100	🔴 较差
性能（桌面设备）	52/100	🔴 较差

核心指标（移动设备）：

指标	数值	评级
首次内容绘制	11.9 s	🔴 较差
最大内容绘制	13.4 s	🔴 较差
总阻塞时间	30 ms	🟢 优秀
累积布局偏移	0.07	🟢 良好
速度指数	11.9 s	🔴 较差

CrUX 实际用户数据——github.com 源站（手机）：

指标	p75（实际用户）
首次内容绘制	1.9 s
最大内容绘制	2.2 s
下一次绘制交互	243 ms
累积布局偏移	0.02

每次运行的结果可能有所不同——Lighthouse 实验室数据存在噪声（单次运行只是一个样本）。要获得中位数，请使用 runs: 3-5。

实验室数据与现场数据：Lighthouse 会限制网络连接速度（因此移动设备评分为 54/100），而 CrUX 展示了 GitHub 访客的实际体验——这两种视角都直接来自此服务的工具。

📚 文档

我们提供了完整的在线文档。

👉 查看完整文档网站

• 🚀 入门指南
• 🛠️ 工具参考
• 🏗️ 架构

你也可以在 docs/ 目录中查看原始 Markdown 文件，或在本地运行 mkdocs serve。

📝 发布说明

当前版本：请参阅此 README 顶部的版本徽章。

最新亮点：

• ✨ 丰富美观的可视化格式：

  • Unicode 分数条：进度可视化仪表盘（█████████████░░░ 85/100 🟢 Good），即时反馈。
  • Core Web Vitals 评分卡：简洁的 Markdown 表格，依据 Google 2026 年官方指南分类（🟢 Good、🟡 Needs Improvement、🔴 Poor）。
  • GitHub Shield 徽章：可直接复制到代码仓库 README 中的 Markdown 徽章，附带直接指向 web.dev 分析的链接。
  • 现代化 Mermaid 架构图：高对比度、适合深色模式的流程图，节点按颜色分类。
  • 建议提示卡：可视化优先级摘要卡片（🔴 High | 🟡 Medium | 🟢 Low | Impact: High）。

• 💬 原生 MCP 提示词（斜杠命令）：

  • 向 Claude Desktop、Cursor 和 Cline 的斜杠菜单提供交互式提示词：
    • /performance-audit：循序引导的 4 步性能问题排查，并提供优先级排序的修复建议。
    • /release-comparison：验证预发布环境与生产环境之间的差异，并给出明确的 GO / NO-GO 决策。
    • /core-web-vitals-deepdive：深入对比真实用户 CrUX 现场数据与合成 Lighthouse 实验室模拟数据。

• 📚 原生 MCP 资源：

  • 无需执行工具即可直接使用的上下文 URI：
    • pagespeed://web-vitals-guide：2026 年 Core Web Vitals 阈值与优化指南。
    • pagespeed://baselines：本地记录的性能基线，用于跟踪回归。

• 🧪 企业级测试套件与弹性：

  • 扩展测试覆盖范围，包含 21 个测试套件和 304 个测试（全部通过）。
  • 高覆盖率标准：96.43% 语句覆盖率、85.82% 分支覆盖率（格式化器、资源和基线均达到 100%）。
  • 在 CI 和 prepublishOnly 中实现干净的单次运行（lint、typecheck、test、build）。

• v2 核心架构：

  • 六个面向工作流的 pagespeed_* 工具取代了旧版 19 个面向端点的工具；所有数据工具均支持 Markdown 或 JSON 格式，并返回结构化结果。

本 README 顶部的徽章会在每次发布时自动更新（npm 版本、GitHub 软件包版本、下载量）。无需手动编辑。

如需查看完整发布历史，请参阅 CHANGELOG.md。

🎯 为什么需要它

痛点 1 —“我的页面很慢，但我不知道原因。” 你打开 PageSpeed Insights，看到一大堆数据，却仍然不知道该先修复什么。这个 MCP 为你的 AI 助手提供六种专注的工作流，帮你从繁杂信息中找到重点：它会找出确切的渲染阻塞资源、浪费 2 MB 的具体图片、占用主线程 1.5 s 的第三方脚本，并按影响程度排序。询问“为什么我的网站很慢？”，即可获得按优先级排列的修复清单，而不是包含 40 项指标的仪表盘。

痛点 2 —“我把性能回归问题带到了生产环境。” 团队快速推进、每天部署，却没人会在每次合并前运行完整的 Lighthouse 审计。等有人发现 Core Web Vitals 下降时，回归问题早已上线。这个 MCP 让任何开发者都能将 URL 粘贴到 Claude/Cursor 中，并在几秒内获得完整审计结果——实验室数据、来自真实 Chrome 用户的现场数据（CrUX），以及元素级 CLS/LCP 调试。这意味着可以在办公桌前发现回归问题，而不是三天后才收到 SEO 团队发来的 Slack 消息。

✨ 功能

核心功能

• 🚀 使用 Google PageSpeed Insights 分析网页性能
• 📱 多平台支持：移动设备和桌面设备
• 🔍 详细的 Lighthouse 报告，包含全面的指标
• 📊 精简报告，突出关键性能指标
• 🎯 智能建议，提供优先级评分和可执行的修复方案
• 💾 智能缓存，减少 API 调用并提升性能
• 🌍 本地化——支持多种语言
• ⚡ 快速安装——一条命令即可完成设置
• 🐳 Docker 支持，适用于容器化部署

高级分析工具（全新！）

• 📸 视觉分析 - 截图、胶片条和整页捕获
• 🎯 元素级调试 - 查找导致问题的特定 DOM 元素
• 🌐 网络瀑布图 - 详细的请求计时和资源加载情况
• ⚡ JavaScript 性能分析 - 执行情况细分和未使用代码检测
• 🖼️ 图像优化 - 定位具体图像问题并显示准确的节省量
• 🚫 渲染阻塞分析 - 关键请求链和依赖项
• 🔌 第三方影响 - 按提供方分组显示脚本影响
• 📊 完整审计 - 对所有类别进行完整的 Lighthouse 审计

🚀 快速安装

选项 1：自动安装（推荐）

# Set environment variable
export GOOGLE_API_KEY=your-google-api-key

curl -sSL https://raw.githubusercontent.com/ruslanlap/pagespeed-insights-mcp/master/scripts/install.sh | bash

安装程序默认使用公共 npm 包（pagespeed-insights-mcp）。若要改为安装带作用域的 GitHub Packages 构建版本，请先配置 GitHub Packages 身份验证，然后运行：

curl -sSL https://raw.githubusercontent.com/ruslanlap/pagespeed-insights-mcp/master/scripts/install.sh | \
  PAGESPEED_INSIGHTS_MCP_PACKAGE=@ruslanlap/pagespeed-insights-mcp bash

选项 2：通过 npm 或 GitHub Packages 安装

从 npm（公共注册表）安装

# Global installation from npm
npm install -g pagespeed-insights-mcp

# Or use without installation
npx pagespeed-insights-mcp

从 GitHub Packages 安装

# First configure authentication (see GITHUB_PACKAGES.md for details)
# Then install globally
npm install -g @ruslanlap/pagespeed-insights-mcp

注意： 此包同时发布在 npm 和 GitHub Packages 上。

• 对于 npm：使用 npm install pagespeed-insights-mcp
• 对于 GitHub Packages：使用 npm install @ruslanlap/pagespeed-insights-mcp（需要 GitHub 身份验证）

有关从 GitHub Packages 安装的详细说明，请参阅 GITHUB_PACKAGES.md，或访问 GitHub Packages 页面

🔧 配置

MCP 服务需要 Google API 密钥才能访问 PageSpeed Insights API。

# Set environment variable
export GOOGLE_API_KEY=your-google-api-key

# Windows
$env:GOOGLE_API_KEY="your-google-api-key"

# Or pass directly when running
GOOGLE_API_KEY=your-google-api-key npx pagespeed-insights-mcp

📝 MCP 配置示例

Claude Desktop（使用 pino-pretty 日志记录）：

"pagespeed-insights": {
  "command": "npx",
  "args": [
    "-y",
    "-p",
    "pino-pretty",
    "-p",
    "pagespeed-insights-mcp",
    "pagespeed-insights-mcp"
  ],
  "env": {
    "GOOGLE_API_KEY": "your-google-api-key-here"
  }
}

Codex（使用 pino-pretty 日志记录）：

[mcp_servers.pagespeed-insights]
command = "npx"
args = [
  "-y",
  "-p",
  "pino-pretty",
  "-p",
  "pagespeed-insights-mcp",
  "pagespeed-insights-mcp"
]
env = { GOOGLE_API_KEY = "your-google-api-key-here" }

注意： 这些示例包含 pino-pretty，可改善日志格式。有关不使用美化日志的生产环境用法，请参阅下方的日志记录部分。

Google Antigravity

示例配置文件位于 examples 目录中。

选项 3：Docker

docker build -t pagespeed-insights-mcp .
docker run -e GOOGLE_API_KEY=your-key pagespeed-insights-mcp

🔑 获取 Google API 密钥

要使用此 MCP 服务，您需要一个已启用 PageSpeed Insights API 的 Google API 密钥。

提示

⚡ 快速设置链接： 您可以直接前往 Google Cloud 凭据设置页面，快速在项目中创建密钥。

分步指南

1. 前往 Google Cloud Console（或使用快速设置链接）。
2. 创建新项目，或选择现有项目。
3. 启用 PageSpeed Insights API：
   • 前往 API 和服务 → 库。
   • 搜索 "PageSpeed Insights API"，然后点击 启用。
4. 创建 API 密钥：
   • 前往 API 和服务 → 凭据。
   • 点击 创建凭据 → API 密钥。
   • 复制生成的密钥，并在配置中将其设为 GOOGLE_API_KEY。

⚙️ Claude Desktop 配置

配置路径：macOS ~/Library/Application Support/Claude/claude_desktop_config.json · Windows %APPDATA%\Claude\claude_desktop_config.json · Linux ~/.config/claude/claude_desktop_config.json — JSON 配置请参阅上方的⚙️ 客户端配置。编辑后重启 Claude Desktop。

💻 用法

完成配置后，只需向 Claude 提出以下任一请求：

🔍 整页分析

Analyze the performance of https://example.com

📱 移动设备分析

Analyze https://example.com for mobile devices with all categories

⚡ 性能快速概览

Get a quick performance report for https://example.com

🖥️ 桌面分析

Analyze https://example.com performance for desktop devices

🌐 多类别分析

Perform a full audit of https://example.com including SEO, accessibility, and best practices

🎯 智能性能建议

Get smart recommendations for improving https://example.com performance

💾 缓存管理

Clear the cache to get fresh data for all subsequent requests

📸 视觉分析

Get visual analysis for https://example.com showing screenshots and loading timeline

🎯 元素级调试

Show me which specific elements are causing performance issues on https://example.com

🌐 网络瀑布图分析

Analyze the network requests and resource loading for https://example.com

⚡ JavaScript 性能

Get JavaScript execution breakdown for https://example.com

🖼️ 图像优化机会

Show me which images need optimization on https://example.com

🚫 阻塞渲染的资源

Find render-blocking resources on https://example.com

🔌 第三方脚本影响

Analyze third-party script impact on https://example.com performance

📊 完整 Lighthouse 审计

Run a full audit including accessibility, SEO, and best practices for https://example.com

可用工具（v2）

版本 2 将原先 19 个按端点划分的工具替换为 6 个工作流工具。这是一次破坏性变更：请更新 MCP 客户端提示词、已保存的工具调用和集成，以使用以下名称。每个返回数据的工具都接受 responseFormat（markdown 为默认值，或 json），并返回 MCP structuredContent。

工具	用途
pagespeed_analyze_page	单页 Lighthouse 健康检查、完整报告、建议、审计结果或 Mermaid 图（report）。
pagespeed_diagnose_page	一项专项调查：visual、elements、network、javascript、images、render-blocking 或 third-parties。
pagespeed_get_field_data	获取 page 或 origin 的 CrUX 真实用户 Core Web Vitals。
pagespeed_compare_pages	立即比较两个页面，或将一个页面与其已保存的基线比较（mode）。
pagespeed_analyze_batch	对 1–10 个页面进行初步分析，并在支持时发送进度通知。
pagespeed_clear_cache	部署后清除当前进程的内存 API 缓存。

从 v1 迁移

v1 工具	v2 替代工具
analyze_page_speed、get_performance_summary、get_recommendations、get_full_audit、get_performance_map	使用 pagespeed_analyze_page，并将 report 设为 full、summary、recommendations、audit 或 performance-map
get_visual_analysis、get_element_analysis、get_network_analysis、get_javascript_analysis、get_image_optimization_details、get_render_blocking_details、get_third_party_impact	使用 pagespeed_diagnose_page，并将 focus 设为对应项
crux_summary、get_origin_crux	使用 pagespeed_get_field_data，并将 scope 设为 page 或 origin
compare_pages、compare_baseline	使用 pagespeed_compare_pages，并将 mode 设为 pages 或 baseline
batch_analyze、clear_cache	pagespeed_analyze_batch、pagespeed_clear_cache
full_report	运行 pagespeed_analyze_page 和 pagespeed_get_field_data；实验室数据和现场数据会明确区分，不会混在一起。

示例

{"url":"https://example.com","strategy":"mobile","report":"recommendations","responseFormat":"markdown"}

{"url":"https://example.com","focus":"render-blocking","responseFormat":"json"}

{"mode":"baseline","url":"https://example.com","strategy":"mobile","runs":3}

示例

Claude Desktop 使用 pagespeed-insights-mcp 的回答示例 🔥🔥🔥

MCP 提示词（斜杠命令）

此服务提供内置的 MCP 提示词，会自动显示在 Claude Desktop、Cursor 和 Cline 的提示词／斜杠菜单（/）中：

提示词	描述	参数
performance-audit	引导式的 4 步性能分析：Lighthouse 摘要、CrUX 现场数据、针对性诊断，以及按优先级排序的修复工单。	url（必需）、strategy（mobile／desktop）
release-comparison	自动化的发布前比较：对比预发布环境与生产环境，提供趋势指标和明确的 GO / NO-GO 发布建议。	productionUrl（必需）、stagingUrl（必需）、strategy
core-web-vitals-deepdive	深入调查 LCP、INP 和 CLS 的真实用户 CrUX 指标与模拟 Lighthouse 实验室评分之间的根本原因。	url（必需）、scope（page／origin）

MCP 资源

通过标准 MCP 资源 URI 直接访问参考指南和本地状态：

资源 URI	MIME 类型	内容
pagespeed://web-vitals-guide	text/markdown	2026 年官方 Core Web Vitals 阈值（良好／需要改进／较差），涵盖 LCP、INP、CLS、FCP、TTFB 和 TBT。
pagespeed://baselines	application/json	由 pagespeed_compare_pages 记录并存储在本地的性能基线。

✨ 丰富的视觉与美感输出

返回到 Claude Desktop、Cursor 和 Cline 的输出采用丰富的美观格式：

• Unicode 分数条：可视化进度（例如 \█████████████░░░` 85/100 🟢 (良好)`）。
• Core Web Vitals 评分卡：采用清晰状态徽章的表格，包含 2026 年官方目标（🟢 良好、🟡 需要改进、🔴 较差）。
• README 徽章：可直接复制粘贴到仓库的 Markdown 徽章（[![PageSpeed Score](https://img.shields.io/badge/PageSpeed-95%2F100-success?style=flat-square&logo=lighthouse)](https://pagespeed.web.dev)）。
• 现代化 Mermaid 架构图：高对比度、适合深色模式的流程图，节点采用颜色编码。

开发

为了在开发过程中获得更好的日志格式，建议全局安装 pino-pretty：

npm install -g pino-pretty

# Development mode
npm run dev

# Build project
npm run build

# Run built server
npm start

MCP 环境中的日志记录 / pino-pretty

此 MCP 服务使用 pino 记录日志，并在 NODE_ENV=development 时启用 pino-pretty 传输器。

• 如果你只想尽量减少设置，让它直接运行（Claude、Codex 等），请设置：

NODE_ENV=production GOOGLE_API_KEY=your-google-api-key npx pagespeed-insights-mcp

或在 MCP 配置中设置：

"pagespeed-insights": {
  "command": "npx",
  "args": ["pagespeed-insights-mcp"],
  "env": {
    "GOOGLE_API_KEY": "your-google-api-key-here",
    "NODE_ENV": "production"
  }
}

• 如果你想在开发过程中通过 npx 美化日志，可以让 npx 在安装此服务的同时安装 pino-pretty：

"pagespeed-insights": {
  "command": "npx",
  "args": [
    "-y",
    "-p",
    "pino-pretty",
    "-p",
    "pagespeed-insights-mcp",
    "pagespeed-insights-mcp"
  ],
  "env": {
    "GOOGLE_API_KEY": "your-google-api-key-here"
  }
}

故障排除

“未提供 Google API 密钥”

请确保已在 Claude Desktop 配置中设置 GOOGLE_API_KEY 环境变量。

“PageSpeed Insights API 错误：403”

请检查 Google Cloud 项目是否已启用 PageSpeed Insights API。

“URL 无效”

请确保 URL 包含协议——仅接受 http:// 和 https://。其他协议（file://、ftp://、javascript: 等）会在架构层被拒绝。

要求

• Node.js 20.19.0 或更高版本（Node 18 自 2025 年 4 月起已结束生命周期，不再受支持）。
• 一个已启用 PageSpeed Insights API 和（可选）Chrome UX Report API 的 Google API 密钥。

安全

请私下报告安全问题——不要公开提交 issue。有关披露政策和运营者安全加固说明，请参阅 SECURITY.md。

致谢

特别感谢 @engmsaleh（Mohamed Saleh Zaied）为本项目开发作出的重要贡献。

特别感谢 @system-conf 为本项目的发展壮大作出的卓越且宝贵的贡献。你们的投入、专业知识和持续支持带来了巨大影响——没有你们，本项目就不会有今天的成就。🙏

许可证

Apache-2.0——请参阅 LICENSE。贡献者根据 Apache License 2.0 授予专利许可。

支持

如需报告 Bug 或提出功能请求，请在仓库中创建 issue。