How I Connected PageSpeed Insights to Claude with MCP

What this server is and why bother

MCP (Model Context Protocol) is an open protocol that lets an AI assistant call external tools; I covered it in more detail in the post about connecting Search Console. What matters here is simple: an MCP server is a go-between program on your computer. On one side it talks to the assistant, on the other it queries the Google PageSpeed Insights API, the same Lighthouse engine that powers the report on the PageSpeed website. Claude asks for a test on its own, gets the numbers and interprets them, and all I have to do is ask questions in plain words.

The server also does things the web version does not: it compares two pages, tests up to ten addresses at once, and stores a baseline measurement to check new results against.

Which server I chose and what I checked before installing

I picked pagespeed-insights-mcp, an npm package written in TypeScript, version 2.1.0. Three things decided it:

• Six clear tools instead of a sprawl. Page analysis, diagnosis through a single “lens”, real-user data, comparison, batch testing and a cache reset. Nothing extra.
• Ready-made reports for the task. Instead of Google’s raw 850 KB response you get a summary, a fix list sorted by importance or a breakdown of render-blocking resources. That is easier for the model and uses fewer tokens.
• Short, readable code. You can review it in an evening instead of guessing what someone else’s program does.

I read all of the code before installing, which is my habit with any MCP server. It is licensed under Apache-2.0. The network footprint is two Google addresses only: the PageSpeed Insights service and Chrome UX Report. The API key is stripped from logs and error messages, retries back off with growing pauses, no more than three requests run in parallel, and responses are cached for an hour. Why this kind of review is not a formality is covered in the post on AI tool security.

Step 1. The Google key: separate and restricted

The service is free but will not run without a key: the shared anonymous quota is used up, and my very first request returned error 429, meaning the request limit was exceeded. You need an API key from a Google Cloud project.

1. In your Google Cloud project, enable the PageSpeed Insights API. I already had a project, the same one used for Google Analytics and Search Console, and this API was already enabled in it.
2. Under “Credentials”, create an API key and give it a clear name.
3. In the key restrictions, choose “Restrict key” and tick the interfaces you need, instead of leaving “Don’t restrict key”.

I did not extend any of the project’s existing keys: each has its own job, and the key for indexing should not be able to reach speed tests. A separate key is also a separate revocation: if something goes wrong you switch off one key instead of working out which services depend on it. I set no restriction by IP address or website, since the server runs on my computer with a changing address.

One pitfall cost me an extra round: the Chrome UX Report API, which provides real-visitor data, is switched off in the project by default, even when PageSpeed already works. Until you enable it and add it to the key restrictions, the real-user tool answers with a 403 and the reason API_KEY_SERVICE_BLOCKED. Checking this with a direct request to the API is more reliable than guessing from the server’s message.

Step 2. Installation

You need Node.js version 20.19 or newer. Check it:

node --version

Install the package globally:

npm install -g pagespeed-insights-mcp

The installation took about 20 seconds and pulled in 127 dependency packages. A program called pagespeed-insights-mcp appeared on the command line, and that is the server. You do not need to start it by hand: Claude launches it.

Step 3. Registering it in Claude Code

The key is passed through an environment variable. In PowerShell:

$k = "your_google_key"
claude mcp add `
  pagespeed-insights -s user `
  -e "GOOGLE_API_KEY=$k" `
  -e NODE_ENV=production `
  -- pagespeed-insights-mcp

The -s user flag writes the entry to the user configuration rather than the project file: the project folder syncs to the cloud, and the key has no business being there. NODE_ENV=production switches the logs from coloured text to compact JSON, which is easier to analyse if something goes wrong. Now check it:

claude mcp list

“Connected” appeared next to pagespeed-insights. Then came the story familiar from Search Console: an already open session has no new tools, because the list is loaded at start. Also, “Connected” only means the process started and answered the handshake, not that the key works and the API is enabled. So I first tested the key with an ordinary request to the PageSpeed API: a 200 response and a full report for the home page. Only then did I open a new session.

The six tools in plain words

• Page analysis. A full Lighthouse test: scores for speed, accessibility, SEO and best practices. You can ask for a summary, a full breakdown or a fix list by priority.
• Diagnosis. One “lens” of your choice: render-blocking resources, images, scripts, third-party code, network, visual loading, page elements.
• Real-user data. Metrics from the Chrome UX Report: what live visitors experience, not a lab measurement.
• Comparison. Two pages against each other, or a page against its own earlier measurement; the baseline is stored in a file in the user’s home folder.
• Batch testing. Up to ten addresses in one call, with a summary for each.
• Cache reset. The server keeps responses for an hour; after you change the site, reset the cache or you will get an old measurement.

What the first run showed on my own site

I tested the studio’s home page with the mobile profile. Scores: performance 66–71 out of 100 (varying between runs), accessibility 90, best practices 100, SEO 100. The weakest spots among Google’s main metrics (Core Web Vitals) were the time until the main block appears (LCP), 5.0–5.3 s against a target of 2.5 s or less, and the layout shift during loading (CLS), around 0.13 against a target of 0.1 or less.

The render-blocking diagnosis named ten files: template styles and scripts the browser must download before it can show the page. Together they delayed rendering by about 1.9 s. The heaviest were the theme’s main stylesheet (about 81 KB) and the UIkit script (about 50 KB). On top of that came unused code, roughly 101 KB of styles and 49 KB of scripts, and, as a separate line, needless redirects costing about 0.75 s. This is the page builder’s template, not my own code, so the fix lies in build and cache settings rather than in editing files.

Testing two pages at once showed a spread that is easy to miss by hand: the home page scored 69 and the SEO page 85 (LCP 3.2 s, no layout shifts). Comparing the Russian and English home pages gave 66 versus 71. The Chrome report returned no real-user data for the domain, only “insufficient traffic”. For a small site that is normal, not a fault: only addresses with enough Chrome visits make it into the report.

The potholes I hit

• 429 without a key. Google’s anonymous quota is shared and almost always used up, so “trying it without a key” is not an option.
• 403 on real-user data. A key restricted to one interface will not let another through: enable the Chrome UX Report API separately and add it to the key restrictions.
• No new tools in the old session. After claude mcp add, open a fresh session.
• Scores wander. The measurement is a lab test on a reference phone, and a few points of difference between runs is normal: I got 66 and 71 on the same page. One run proves nothing. The tools have a “number of runs” parameter (up to five), and the server itself waits about a minute between runs, otherwise Google would return the same result.
• A one-hour cache. Fixed the site? Reset the server’s cache before measuring, or you will be comparing yourself with yourself.
• The “changes data” flag on comparison is about a local file. It refers only to the baseline file in your home folder. The tool does not touch your site or any Google service.

What proved useful and what did not

• Works right away: finding the causes of slowness, a fix list by importance, comparing pages of one site, batch testing. The assistant picks the right tool for the question and translates the report out of jargon.
• Needs preparation: real-user data means enabling one more API and having enough traffic.
• With caveats: this is measuring, not treating. The server changes nothing on the site. It shows what slows it down, and fixing it is still up to you or a developer. What you gain is a fix list in a minute instead of half an hour in a report.
• Always remember: only public pages are tested. A customer account or anything behind a password is invisible to the service.

Quick checklist

1. Make sure Node.js 20.19 or newer is installed.
2. Enable the PageSpeed Insights API (and the Chrome UX Report API if you want real-user data).
3. Create a separate API key and restrict it to the interfaces you need.
4. Install the pagespeed-insights-mcp package with npm.
5. Register the server with claude mcp add in the user scope.
6. Test the key with an ordinary request and open a new Claude session.
7. For a before-and-after comparison, ask for three to five runs instead of one.

If you would rather not walk this path yourself, we can connect PageSpeed Insights to an AI assistant for you — on your computer or in your company cloud.