PageSpeed Insights MCP

Measures a web page with Google PageSpeed Insights and reports the median of several runs with the spread beside it, so a number arrives with its uncertainty. Works from an assistant that speaks MCP, or from a terminal.

Standard library only. No virtual environment, no pip, no compiled dependency. Clone it and run it.

Docs · Install · FAQ

Why another one

There are already several PageSpeed MCP servers. As far as we can tell, every one of them only runs Lighthouse once and hands the model the number.

A single Lighthouse run is noise. Total Blocking Time routinely swings threefold between runs on a page that has not changed, and the headline performance score is a weighted blend that inherits every bit of that. Ask once and you get a figure with no error bars, and no way to tell a real regression from the instrument moving. That is not a small imprecision, it is the difference between measuring something and guessing at it confidently.

There is a second problem underneath, and it is worse because it is invisible. PageSpeed caches its result per URL and replays it. Ask five times and you can be handed one analysis five times, which quietly turns a median into a vote for whatever Google happened to have cached. Minutes after a deploy on 30 July 2026 that is exactly what happened here, 2 of 3 runs came back with a byte-identical timestamp from before the deploy, dragging the average back to the pre-fix score while the one fresh run showed the fix working. A tool that reports one run would have reported the stale number as current, with nothing to indicate anything was wrong.

This one takes the median of 5 runs by default, prints the min-max spread next to every figure, drops runs that were cached replays, and tells you how many it dropped.

The lab is not your users

Both of these are true, measured on the same page on the same afternoon.

That is the BBC home page. The lab says the site is catastrophically slow. Real people are getting it in 1.2 seconds.

Neither number is wrong, they answer different questions. Lighthouse is a simulation on throttled hardware, useful because it is repeatable and you can run it against a page nobody has visited yet. Field data is what actually happened to real Chrome users, and it is the only thing Google ranks on. A tool that shows you one and not the other is misleading you, whichever one it picks.

So this reports both, separately, and never merges them into a single figure.

What it does

• Median of N distinct analyses, with the min-max spread beside every score and metric.
• Keeps asking until it has N genuinely different analyses, because Google re-analyses a URL about once a minute and replays the cached result to everything that asks in between. Five requests in a row is one measurement five times over.
• Says what that cost in calls and seconds, and reports fewer analyses honestly rather than padding the count when time runs out.
• Real-user data from the Chrome UX Report, current and up to 6 months of weekly history, when Google has it.
• Says plainly when Google has none, rather than letting a lab score stand in for evidence about real visitors.
• Tells an exhausted quota apart from a broken page, and a misconfigured key apart from both.

Things to actually ask it

Four that exercise different parts of it, and none need you to know a tool name.

"How fast is considus.com on mobile, and how confident are you in that number?" The whole reason this exists. You get the median of several genuinely distinct analyses and the spread around it, not one run quoted as fact.

"Is there real user data for this site, or only lab numbers?" Reads the Chrome UX Report, which is the only evidence here about actual visitors and the only thing Google ranks on. Plenty of small sites have none, and it says so rather than letting a lab score stand in.

"What's actually holding up the LCP on that page?" Splits one number into the four phases it is made of, so you find out whether it is the server, the discovery, the download or the paint. Fast, one call, no averaging needed.

"Did that change help?" Records a baseline on the first call, then compares after you have made the change. It only calls a difference real when the two ranges do not overlap, which is what stops you celebrating the instrument moving.

Before you start

You need an API key from Google Cloud. It is free, it takes about a minute, and there is one decision to make, at step 3.

1. Open console.cloud.google.com and pick your account.
2. APIs & Services.
3. API Library in the sidebar. Search for PageSpeed Insights API, select it, press Enable.

   Decide here, while you are on this screen. If you also want real-user data, meaning what actual Chrome visitors experienced and how it has moved over the last six months, search for Chrome UX Report API and enable that as well before moving on. Same key, no second credential, one more search on the screen you are already looking at. Skip it and everything else still works, you just get lab measurements only. Adding it later means coming back to this screen and to step 7, which is the only reason it is worth deciding now.

4. Credentials, from the sidebar, not from the page you are on.
5. Create credentials at the top, then API key.
6. Give it a name.
7. Under API restrictions, tick PageSpeed Insights API, and tick Chrome UX Report API too if you enabled it at step 3.
8. Leave Authenticate API calls through a service account unticked.
9. Leave Application restrictions on None.
10. Create, then copy the key.

Step 4 is the one that defeats people, and it defeated me. There are two routes to a credentials screen and only one of them offers an API key. Reach it from the page you are already on and the button gives you OAuth clients and service accounts, no API key anywhere, and you reasonably conclude PageSpeed does not support them. It does. The sidebar entry is a different screen, and it sits just below API Library.

Step 9 looks wrong and is not. An HTTP-referrer restriction is the safe-looking choice on that form, and it makes the key unusable from a program like this one, because there is no referring web page. The API restriction at step 7 is the one that limits what the key can reach.

Install

Whichever route you take, clone it somewhere permanent, a folder in your home directory is right. Your assistant's config will point at that exact path, so a folder that later moves is a connection that breaks. Not Downloads, not a temp folder.

Both routes finish the same way. setup.py opens a small page in your browser, served from your own machine on a random port behind a single-use link. It shuts itself down when you are finished and it never writes down anything you type. Paste the key in. It checks the key against Google before saving a thing, and tells you whether real-user data is available.

Run it again any time. It notices you have set it up before, and a blank key field means keep the one you have.

Have an assistant do it

Paste this into an AI assistant that runs shell commands on this computer. Read what it proposes before you let it run.

Please install the PageSpeed Insights MCP server from
https://github.com/Considus/pagespeed-insights-mcp on this computer, following the
Install section of its README exactly. Clone it into a permanent folder in my home
directory, then run setup.py and tell me the local link it prints so I can finish
setup in my browser. Show me each command before you run it.

Or run the commands yourself

Python 3.9 or newer, which macOS and most Linux machines already have. On Windows, install it from python.org or run winget install Python.Python.3.12.

git clone https://github.com/Considus/pagespeed-insights-mcp.git
cd pagespeed-insights-mcp
python3 setup.py

Connect it to your assistant

When setup finishes it hands you a second prompt. Paste that into whichever assistant you want measuring your pages, Claude, Cursor, Windsurf, Zed, Codex CLI, VS Code Copilot, anything that speaks MCP. Restart the app afterwards, MCP servers load at startup.

It works this way round on purpose. Every client keeps its MCP config somewhere different, under a different key, and those locations move. An assistant already knows where its own config lives, so asking it beats shipping a list of paths that quietly rots. The prompt carries no key, only the name, the command and the path.

Tools