Pagespeed Insights

@pipeworx/pagespeed-insights

Google 的 PageSpeed Insights——在 Google 自己的基础设施上对任意公开 URL 运行 Lighthouse，并返回性能／无障碍／最佳实践／SEO 评分、对应的实验室计时指标，以及具体修复项的排名列表和每项可节省的毫秒数或字节数；此外还会返回该页面及其来源站点的 Chrome UX Report 真实用户数据。

属于 Pipeworx 的一部分——一个将 AI Agent 连接到 1683+ 个实时数据源的 MCP 网关。

工具

• pagespeed_audit(url, strategy?, categories?, max_opportunities?, locale?) — 实验室测试及其机会项排名。
• pagespeed_field_metrics(url, strategy?) — 页面 及其来源站点的真实用户 Core Web Vitals，并附上 Google 的通过／未通过判定。

身份验证

自带密钥，并支持平台回退：使用 _apiKey；或者在网关上设置了该密钥时使用 PLATFORM_GOOGLE_API_KEY。

文档中提到的免密钥方式存在，但无法使用。 不带密钥的请求会计入一个由所有人共用的 Google 匿名使用方项目，其每日配额已耗尽——连续三次不带密钥的调用均返回 HTTP 429，错误为 "Quota exceeded … for consumer 'project_number:583797351490'"（于 2026-09-17 实时验证）。所有互联网匿名调用者使用的项目编号都相同，因此我们无法控制其配额，重试也无济于事。该工具包会先尝试免密钥调用，失败后会提示必须提供密钥。

密钥免费、可立即获取，且无需结算账号：前往 https://console.cloud.google.com/apis/credentials 创建密钥，并在 https://console.cloud.google.com/apis/library/pagespeedonline.googleapis.com 启用 PageSpeed Insights API。配额为每天 25,000 次请求、每分钟 240 次。同一密钥也可用于 chrome-ux-report 工具包。

与 chrome-ux-report 工具包的关系

chrome-ux-report 会报告真实访客的体验；它无法说明 原因，因为现场数据不包含诊断信息。此工具包会运行页面并指出问题所在。使用 crux 回答“真实用户访问这个网站时速度快吗”，使用此工具包回答“具体是什么导致它变慢，我应该先修复什么”。

数据源

• https://www.googleapis.com/pagespeedonline/v5/runPagespeed

陷阱，已于 2026-09-17 实时验证

• 一次调用需要 10–40 秒。 Google 会实际加载页面。工具包设置了明确的 60 秒时限；一次批量处理十个 URL 的调用可能需要几分钟。
• 实验室数据与现场数据经常不一致，但两者都正确。 实验室测试是在 Google 数据中心使用限速模拟手机加载一次；现场数据则涵盖真实设备上 28 天的真实访问。实验室评分为 95，但现场 CWV 未通过，意味着真实用户使用的设备比模拟设备性能更差——而 Search 使用的是现场数据。两类数据会分别返回并标明，绝不会混在一起。
• loadingExperience 对应页面，originLoadingExperience 对应网站——对于流量较低的 URL，Google 会在 页面数据块中填入来源站点的数据，并将 origin_fallback 设为 true。若将其误读为页面数据，就会把整个网站的性能归因于某个 URL。此处将其报告为 is_origin_fallback。
• 类别评分是 0–1 的浮点数，而非 0–100，且可能为空。 某个类别出错时会返回 null，而非零。
• 无法访问目标会导致 Google 返回 HTTP 400，而非 404 或 5xx；有用的信息隐藏在 error.errors[].reason 中。此处的“Bad request”通常表示“你的网站向 Google 的爬虫返回了 500”。
• 此 API 中的 CLS 是整数 ×100（5 表示 0.05），而 CrUX API 会将相同指标作为十进制字符串返回。工具包会将其规范化为十进制数。

快速开始

添加到你的 MCP 客户端（Claude Desktop、Cursor、Windsurf 等）：

{
  "mcpServers": {
    "pagespeed-insights": {
      "url": "https://gateway.pipeworx.io/pagespeed-insights/mcp"
    }
  }
}

此端点实际提供的内容

https://gateway.pipeworx.io/pagespeed-insights/mcp 上的 tools/list 会返回上表中的工具，以及 Pipeworx 共享元工具——ask_pipeworx、 discover_tools、search_within、remember/recall 和网关范围内的其他工具。因此，你看到的工具数量会多于表中的数量：目前，单个工具包端点除了列出该工具包自己的工具，还会列出大约 30 个共享工具。连接的 initialize 响应会说明确切范围，也是判断当天实际范围的权威依据。

这是有意为之，并非意外的多路复用。元工具可以让范围受限的连接回答该工具包未涵盖的问题——通过 ask_pipeworx 跨整个目录进行路由——无需再添加第二个 MCP 服务。目前无法在不启用这些元工具的情况下挂载工具包端点；如果额外的架构定义带来的上下文开销超过了路由的价值，请只连接一次完整网关，而不是连接多个工具包端点。

你也可以连接完整的 Pipeworx 网关，直接列出所有工具包的工具，而不只是当前工具包的：

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

两个 URL 都连接到同一个网关和相同的 1683+ 个数据源。唯一的区别是直接列出哪个工具包的工具；从任一端点都可以通过 ask_pipeworx 访问所有工具。

没有 MCP 客户端？通过 HTTP 调用

curl -X POST https://gateway.pipeworx.io/v1/tools/pagespeed_audit \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://www.wikipedia.org"}'

首次调用无需账户。检查任意工具：GET https://gateway.pipeworx.io/v1/tools/pagespeed_audit。查找工具：使用 {"query":"..."} 调用 POST https://gateway.pipeworx.io/v1/tools/search_packs。

独立运行（无需网关账户）

此软件包也可以作为本地 stdio MCP 服务运行——无需 Pipeworx 账户，也无需通过网关中转：

{
  "mcpServers": {
    "pagespeed-insights": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-pagespeed-insights"]
    }
  }
}

或者直接运行它，确认服务可以启动：

npx -y @pipeworx/mcp-pagespeed-insights

它通过 stdin/stdout 使用 MCP，并响应 initialize/tools/list/tools/call，但仅限此工具包的工具——不包含上文网关连接额外提供的共享元工具。相同的源代码、相同的工具，但没有 ask_pipeworx 路由。

使用 ask_pipeworx

你可以用通俗易懂的语言提问，而不是直接调用工具——这既适用于上文的工具包端点，也适用于完整网关：

ask_pipeworx({ question: "your question about Pagespeed Insights data" })

网关会自动选择合适的工具并填入参数。

更多信息

• 文档和指南
• pipeworx.io

许可证

MIT