Integration

Connect PageSpeed Insights to Claude Code

The usual way to give Claude Code PageSpeed data is a local script and a Google Cloud API key. GenieSeo hosts 2 PageSpeed Insights tools instead: no key, no quota juggling, and real-user Core Web Vitals in the response, so Claude Code can measure a slow page and then fix it in your repo.

Why not call the API yourself?

No API key in your config

Unauthenticated PageSpeed requests hit a low quota quickly; the fix is a Google Cloud project, an enabled API and a key in an env var. The hosted server makes the call, so none of that lives on your machine.

Trimmed for an LLM

A raw PageSpeed response is a very large Lighthouse JSON. The tools return category scores, the key lab metrics and field data, which keeps Claude Code's context for your code.

Field data, not just lab

Responses include Chrome UX Report data for the URL and its origin when Google has it. That's what Google's Core Web Vitals assessment uses, and it often disagrees with a single lab run.

Next to Search Console

The same server gives Claude Code your Search Console data, so it can pick which pages to test by clicks instead of guessing.

Add it to Claude Code

Create a GenieSeo account at /signup, then register the server and sign in. The full walkthrough, scopes and troubleshooting are on the Claude Code setup page.

bash
claude mcp add --transport http --scope user genieseo https://seo.geniedial.in/mcp
# then inside Claude Code: /mcp → genieseo → authenticate

The two tools and their arguments

run_pagespeed_insightstests one URL. Mobile is the default because that's how Google mainly evaluates Core Web Vitals. Each extra category adds Lighthouse run time, so ask for accessibility or SEO only when you need them.

python
run_pagespeed_insights(
  url: str,                      # full URL incl. https://
  strategy: str = "mobile",      # "mobile" | "desktop"
  categories: str = "performance"  # comma-separated: performance,
                                   # accessibility, best_practices, seo, pwa
)

compare_pagespeed_insightstests up to five URLs in parallel, for example your page against a competitor's. Each URL is fetched separately, so one blocked page lands in errors while the others still return.

python
compare_pagespeed_insights(
  urls: str,                     # comma-separated, max 5 URLs per call
  strategy: str = "mobile",
  categories: str = "performance"
)

Both return the same per-URL shape:

json
{
  "category_scores":      { "performance": 0-100, ... },
  "lab_core_web_vitals":  { "largest-contentful-paint": {...},
                            "cumulative-layout-shift": {...},
                            "total-blocking-time": {...},
                            "first-contentful-paint": {...},
                            "speed-index": {...}, "interactive": {...} },
  "field_data_this_url":  { "overall_category": ..., "metrics": { ...percentile, category } } | null,
  "field_data_origin":    { "overall_category": ..., "metrics": { ... } } | null,
  "strategy": "mobile"
}

field_data_this_url is often null on low-traffic pages. Tell Claude Code to fall back to field_data_origin and to say which one it used, or it may present origin numbers as if they were page-level.

Worked prompt: audit mobile Core Web Vitals, then fix in code

Run this from the root of your site's repo. It starts from Search Console so you test pages that get traffic, not the homepage by habit.

text
Use genieseo for this.
1. get_search_analytics on sc-domain:example.com, dimension page,
   last 28 days: give me the top 5 pages by clicks.
2. run_pagespeed_insights on each, strategy mobile.
3. Table: page, performance score, lab LCP / CLS / TBT, and field
   data (URL-level if present, otherwise origin, and say which).
4. For the worst page, find the route and components in this repo
   that render it and explain what is most likely driving its LCP
   or CLS. Propose the smallest code change, show the diff, and
   wait for my OK before editing.

To benchmark against a rival instead, the Core Web Vitals vs competitor recipe has a ready-made compare_pagespeed_insights prompt.

When a run fails

"PageSpeed Insights couldn't load that URL"

Lighthouse fetches the page from Google's servers. Localhost, preview URLs behind auth, and pages that block bots or return non-200 status codes can't be tested. Use a public staging URL.

"rejected the URL as invalid"

Include the scheme: https://example.com/page, not example.com/page.

strategy or category errors

strategy must be mobile or desktop. Categories are a comma-separated subset of performance, accessibility, best_practices, seo and pwa (note the underscore).

FAQ

Do I need a PageSpeed Insights API key to use this in Claude Code?+

No. GenieSeo runs the PageSpeed Insights calls on its hosted server, so you don't create a Google Cloud project, enable the API or paste a key into your Claude Code config. You only sign in to GenieSeo once through /mcp.

Is this lab data or real-user data?+

Both. Each call returns Lighthouse lab metrics from that run, plus Chrome UX Report field data for the URL and its origin when Google has enough traffic to report it. Low-traffic pages often return null field data; the origin-level numbers are the fallback.

Can I compare my page against a competitor?+

Yes. compare_pagespeed_insights takes up to 5 comma-separated URLs and returns them side by side. One unreachable URL doesn't fail the others; it shows up in the errors list.

Does PageSpeed count against my GenieSeo plan?+

Each run is one tool call. On the free plan, GA4 and PageSpeed reports share an allowance of 15 calls a month within the 200-call monthly cap.

Measure it, then fix it, in one session.

PageSpeed Insights + Search Console + GA4 · No API key

Related