PageSpeed Insights MCP

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.

1. Credentials, from the sidebar, not from the page you are on.
2. Create credentials at the top, then API key.
3. Give it a name.
4. Under API restrictions, tick PageSpeed Insights API, and tick Chrome UX Report API too if you enabled it at step 3.
5. Leave Authenticate API calls through a service account unticked.
6. Leave Application restrictions on None.
7. 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

Measurements that outlive the call

Every long check used to time out, and the server was fine the whole time. It carried on measuring, finished the job properly, and posted the answer into a pipe nobody was reading any more.

The client had given up at 60 seconds. That is a hard wall on a single tool call, and progress notifications don't move it, which is worth knowing because this server sends them and they look like they should. An honest measurement can't fit inside it. Google re-analyses a URL about once a minute, so five distinct analyses take about 150 seconds, and asking harder doesn't help, it just hands you the same cached analysis five times.

The work doesn't happen inside the call any more. analyse_page and compare_to_baseline start the measurement, hand back a job id, and keep going. Your assistant collects it with get_job_result, every 15 seconds or so, and get_job_result always answers straight away. When the measurement lands it returns exactly what the tool would have returned, so nothing downstream can tell which route it took.

You don't have to do anything. The assistant polls for you.

One measurement still answers on the spot, analyse_page with include set to ["scores"], one URL and runs set to 1. That is a single analysis with no spread, which is the noisy one-run number this whole package exists to refuse, and the output says so in as many words.

A fin