Skip to main content
Glama
PageSpeed Insights MCP Server

PageSpeed Insights MCP Server

PageSpeed Insights MCP Server

Buy Me A Coffee

六工具 MCP 服务器,适用于 Google PageSpeed Insights 与 Chome UX Report API。可通过 Claude、Cursor 或任何兼容 MCP 的 AI 客户端直接分析、比较和优化网页性能。

⚡ 快速开始(复制粘贴)

{
  "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)

npm version npm downloads MCP Toplist Glama MCP

GitHub Package Version CI Documentation Live Demo License: Apache-2.0

Related MCP server: page-speed-insights-mcp

🔥 它为何与众不同

大多数 PageSpeed Insights MCP 服务器只封装一个工具:“对 URL 运行 PSI”。而此服务器提供六个工作流工具,覆盖完整的性能工作流——不仅仅是分数,而是行动计划:

  • 完整工具包:页面分析、CrUX 真实用户数据(URL + 来源)、Lighthouse 审计、多页面与批量对比、基线和回归跟踪

  • 深度诊断:元素级、网络、JavaScript、图像优化、渲染阻塞和第三方影响分析

  • 可操作输出:推荐引擎将原始 Lightouse 数据转化为按优先级排序的修复方案,外加截图视觉分析

  • 实用附加功能:重复运行的缓存,以及针对 AI 代理可执行而优化的智能推荐

  • 久经考验:发布于 npm,列入官方 MCP 注册表 和 Glama,并通过 Vitest 进行 CI 测试

🎬 查看交互式演示 → — 查看带动画示例的工具实战 备用 URL:https://ruslanlap.github.io/pagespeed-insights-mcp/demo.html

📖 目录

  • [⚡ 快速开始(复制粘贴)](#- quick-start-copy--paste)

  • [🔥 它为何与众不同](#- what-makes-it-different)

  • [⚙️ 客户端配置](#- cient-configuration)

  • [📊 示例输出](#- ample-output)

  • [📚 文档](#- ocumentation)

  • [📝 发布说明](#- lease-notes)

  • [🎯 为什么你需要它](#- why-you-need-this)

  • [✨ 功能](#- atures)

  • [🚀 快速安装](#- quick-installation)

  • [🔑 获取 Google API 密钥](#- getting-google-api-key)

  • [⚙️ Claude Desktop 配置](#- claude-desktop-configuration)

  • [💻 使用方法](#- usage)

  • [可用工具](# available-tools)

  • [开发](# development)

  • [故障排除](# troubleshooting)

  • [环境要求](# requirements)

  • [安全](# security)

  • [致谢](# acknowledgments)

  • [许可证](# license)

  • [支持](# support)

客户端配置

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__pagesped_analyze_page、pagespeed-insights__pagespeed_get_field_data 等(带命名空间)

📊 示例输出

针对 github.com 的真实 pagespeed_analyze_page 结果——一次移动端 Lighthouse 运行。CrUX 数字来自 pagespeed_get_field_data(scope : "origin"):

Lightouse 实验室评分:

类别

得分

状态

Performance (mobile)

54/100

🔴 差

Performance (desktop)

52/100

🔴 差

核心指标(移动端):

指标

数值

评级

First Contentful Paint

11.9 s

🔴 差

Largest Contentful Paint

13.4 s

🔴 差

Total Blocking Time

30 ms

优秀

Cumulative Layout Shift

0.07

良好

Speed Index

11.9 s

🔴 差

CrUX 现场数据——真实用户,github.com 来源(手机):

指标

p75(真实用户)

First Contentful Paint

1.9 s

Largest Contentful Paint

2.2 s

Interaction to Next Paint

243 ms

Cumulative Layout Shift

0.02

每次运行的结果都会有所不同——Lightouse 实验室数据存在噪声(单次运行只是一个样本)。请使用 runs: 3-5 获取中位数。

实验室与现场数据对比:Lightouse 会限制连接速度(因此移动端为 54/100),而 CrUX 显示的是真实 GitHub 访问者的体验——这两种视图都直接来自此服务器的工具。

📚 文档

我们提供全面的在线文档。

👉 查看完整文档站点

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

📝 发布说明

当前版本:v2.0.0。

  • v2.0.0——六个面向工作流的 pagespeed_* 工具取代了 19 个 v1 端点式工具;所有数据工具均支持 Markdown 或 JSON 结构化结果。

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

完整的发布历史请参阅 CHANGELOG.md。

为什么你需要它

痛点 1——“我的页面很慢,但不知道为什么。” 打开 PageSpeed Insights,你会得到一屏数据,却仍然不知道先修什么。这个 MCP 为你的 AI 助手提供六个聚焦的工作流,帮你穿透噪音:它会识别出确切的渲染阻塞资源、浪费了 2 MB 的特定图片、消耗主线程 1.5 秒的第三方脚本,并按影响程度排序。问一句“为什么我的网站很慢?”,你得到的是一份按优先级排序的修复清单,而不是 40 项指标的仪表盘。

痛点 2——“我把性能回退发布到了生产环境。” 你的团队节奏很快,每天部署,没有人会在每次合并前运行一次完整的 Lightouse 审计。等到有人注意到 Core Web Vitals 下降时,回退已经上线了。这个 MCP 让任何开发者在 Claude/Cursor 中粘贴一个 URL,就能在几秒内获得完整审计——实验室数据、来自真实 Chome 用户的现场数据(CrUX)、元素级 CLS/LCP 调试。这就好比在工位上发现回退,而非三天后从 SEO 团队的 Slack 消息里才发现。

✨ 功能

核心功能

  • 性能分析:使用 Google PageSpeed Insights 分析网页

  • 📱 多平台支持:移动端和桌面端设备

  • 🔍 详细的 Lightouse 报告,包含全面指标

  • 📊 简化报告,包含关键性能指标

  • 智能推荐,带优先级评分和可操作的修复方案

  • 💾 智能缓存,减少 API 调用并提升性能

  • 🌍 本地化——支持多种语言

  • 快速安装——一条命令完成设置

  • Docker 支持,用于容器化部署

高级分析工具(新!)

  • 📸 视觉分析——截图、胶片条和整页捕获

  • 🎯 元素级调试——查找导致问题的具体 DOM 元素

  • 🌐 网络瀑布流——详细的请求时序和资源加载

  • JavaScript 性能分析——执行分解和未使用代码检测

  • ️ 图像优化——具体图像问题及精确节省量

  • 渲染阻塞分析——关键请求链和依赖关系

  • 🔌 第三方影响——按提供商分组的脚本影响

  • 📊 完整审计——所有类别的完整 Lightouse 审计

🚀 快速安装

选项 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)。如果要改用 scoped 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 密钥。

[!TIP] ⚡ 快速设置链接: 你可以直接前往 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 个端点式工具。这是一个破坏性变更:请更新 MCP 客户端提示、已保存的工具调用和集成,以使用下面的名称。每个返回数据的工具都接受 responseFormat(markdown,默认,或 json),并返回 MCP structuredContent。

Tool

Use it for

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 的示例回答 🔥🔥🔥

开发

为了在开发过程中获得更好的日志格式,建议全局安装 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"
  }
}
  • 如果你希望在开发时通过 nnpx 获得美观的日志,可以让 nnpx 与服务器一同安装 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 月起已结束生命周期(EOL),不再受支持)。

  • 一个已启用 PageSpeed Insights 与(可选)Chrome UX Report API 的 Google API 密钥。

安全

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

致谢

特别感谢 @engmsaleh(Mohamed Saleh Zaied)对本项目开发做出的重要贡献。

非常感谢 @system-conf 对本项目成长与发展所做出的卓越而宝贵的贡献。您的奉献、专业知识和持续支持产生了巨大的影响——没有您,这个项目不会有今天的成就。🙏

许可证

Apache-2.0 —— 请参阅 LICENSE。贡献者依据 Apache License 2.0 授予专利权。

支持

如需报告错误或请求新功能,请在仓库中创建 issue。

Available Tools

6 tools
pagespeed_analyze_batchAnalyze Multiple PagesA
Read-onlyIdempotent

Analyze 1–10 public URLs and return per-page results plus success/failure counts. Use pagespeed_analyze_page for one URL or pagespeed_compare_pages for a direct comparison. Example: triage the ten highest-traffic landing pages. Progress notifications are emitted when supported by the client.

Inputs: urls (required), locale, report, strategy, +2 more. Returns: tool, result, truncated, truncationMessage

pagespeed_analyze_pageAnalyze a Page with LighthouseA
Read-onlyIdempotent

Run a PageSpeed Insights Lighthouse analysis for one public page. Start with report=summary for a health check; choose full for audits, recommendations for a prioritized fix list, audit for non-performance categories, or performance-map for Mermaid. Example: analyze a mobile product page and return the three most useful remediation steps. Returns a report plus structured result. The Google API is contacted and results may be served from the local cache.

Inputs: url (required), runs, locale, report, +3 more. Returns: tool, result, truncated, truncationMessage

pagespeed_clear_cacheClear Local PageSpeed CacheA
Idempotent

Clear only this server process's in-memory PageSpeed response cache, forcing later analysis calls to contact Google again. Use after a deploy when a cached result is stale. It does not change the target website, files, or remote data; repeating the call is safe.

Inputs: no named parameters. Returns: tool, result, truncated, truncationMessage

pagespeed_compare_pagesCompare Pages or a Stored BaselineA
Destructive

Compare two pages now (mode=pages) or measure one page against its locally stored baseline (mode=baseline). Baseline mode records the first call; use runs=3 or more and rely on guaranteed deltas, not medians alone. Example: compare staging against production, or verify whether a deployed fix improved mobile LCP. replaceBaseline overwrites local baseline state.

Inputs: url (required), mode (required), runs, against, +4 more. Returns: tool, result, truncated, truncationMessage

pagespeed_diagnose_pageDiagnose a Page Performance ProblemA
Read-onlyIdempotent

Inspect one page through exactly one diagnostic lens: visual, elements, network, javascript, images, render-blocking, or third-parties. Use after pagespeed_analyze_page identifies a problem; do not use it for a general score. Example: focus=render-blocking to identify CSS/JS delaying first render. Returns focused evidence rather than a full Lighthouse dump.

Inputs: url (required), focus (required), strategy, responseFormat. Returns: tool, result, truncated, truncationMessage

pagespeed_get_field_dataGet Chrome UX Report Field DataA
Read-onlyIdempotent

Get real-user Core Web Vitals from Chrome UX Report, not Lighthouse lab measurements. Use scope=page for one URL; use scope=origin with a bare origin when the page has insufficient traffic. Example: check mobile LCP and INP for https://example.com/checkout. Returns p75 field metrics or a clear no-data result.

Inputs: url (required), scope, formFactor, responseFormat. Returns: tool, result, truncated, truncationMessage

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.7/5.0

    Scored across 6 tools

    Disambiguation4/5

    Each tool has a distinct workflow: single-page analysis, batch analysis, focused diagnostics, field data, comparisons/baselines, and cache control. The only mild overlap is between analyze_page with audit/recommendation reports and diagnose_page, but the descriptions explicitly position diagnose as a follow-up for specific problem areas.

    Naming Consistency5/5

    All tools share a consistent pagespeed_ prefix followed by a clear verb_noun pattern: analyze_page, diagnose_page, get_field_data, compare_pages, analyze_batch, clear_cache. The naming is predictable, uniform, and makes the action and target easy to infer.

    Tool Count5/5

    Six tools is a well-scoped set for a PageSpeed Insights server. Each tool covers a meaningful part of the workflow without redundancy or bloat, and the count feels appropriate for both simple and more advanced performance analysis tasks.

    Completeness5/5

    The tool surface covers the core domain well: single and batch Lighthouse analysis, targeted diagnostics, real-user field data, comparison/baselining, and cache management. There are no obvious dead ends or missing operations that would prevent an agent from completing a typical PageSpeed investigation.

    Maintenance

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Core Web Vitals analysis powered by Lighthouse. Four tools: analyze a URL, compare two URLs, check against thresholds, or crawl an entire site. Works with Claude Code, Cursor, Windsurf, and any MCP-compatible AI tool.
      4
      14 npm
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that wraps the Google PageSpeed Insights API to analyse web performance, providing tools for scores, Core Web Vitals, opportunities, diagnostics, and batch analysis.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      This MCP server integrates Google PageSpeed Insights to analyze website performance, accessibility, best practices, SEO, and PWA on mobile and desktop, returning detailed audits and optimization opportunities.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that pulls PageSpeed Insights and Google Search Console data across multiple owned sites, enabling cross-site performance reports and synthesis via Claude.
      MIT