Google CrUX MCP
Real-user Core Web Vitals from the Chrome UX Report (CrUX) API for any origin or URL.
Google CrUX MCP
English | Русский
A1 Google CrUX MCP brings real-user Core Web Vitals data into an AI app. Check whether a public site or page passes LCP, INP and CLS, compare mobile with desktop, and see how the metrics changed over time.
It reads Google’s Chrome UX Report dataset — field data collected from Chrome users, not a synthetic speed test or a way to change your site.
- 6 read-only tools. Core Web Vitals assessment, device comparison, origin-versus-page comparison, 40-week trend and raw latest or historical records.
- Real-user data. It is the same CrUX field data used by PageSpeed Insights and Google’s Core Web Vitals signals.
- Clear availability boundary. Only public origins and URLs with enough real-user traffic have data;
no_datais a valid result. - Known quota cost. CrUX allows 150 queries per minute per project. Device comparison makes four API calls; origin-versus-page makes two.
Start with a read-only question:
Does
https://example.compass Core Web Vitals on mobile?
Connect the server · Explore use cases · Open technical documentation
See it work in a minute
You: Does
https://example.com/pricingpass Core Web Vitals on mobile?Assistant: Shows p75 LCP, INP and CLS, their good/needs-improvement/poor ratings and the overall result. Nothing changes.
You: Compare this page with the site average and show how mobile differs from desktop.
Assistant: Compares the origin and URL, then device groups and their traffic shares. All six tools read the public CrUX dataset only.
Contents
- Quick start
- What you can ask it to do
- How to read CrUX data
- Getting access
- Configuration
- Data, limits and background work
- Technical documentation
- Support
Quick start
You need Node.js 20+ and a Google Cloud API key with Chrome UX Report API enabled.
- Create a restricted API key.
- Add the server to your AI app.
- Ask the read-only question above.
Codex
In Settings → MCP servers, select Add server, choose STDIO, enter the command npx -y mcp-google-crux@latest and environment variables CRUX_API_KEY, then select Save and Restart.
codex mcp add google-crux --env CRUX_API_KEY=your_key -- npx -y mcp-google-crux@latest
codex mcp list
Claude Code
claude mcp add --env CRUX_API_KEY=your_key --transport stdio --scope user google-crux -- npx -y mcp-google-crux@latest
claude mcp list
Claude Desktop
The current official path is Settings → Extensions. For a custom desktop extension, open Advanced settings → Extension Developer → Install Extension…, select a .mcpb file and follow the prompts.
This repository currently publishes an npm stdio package and does not contain a .mcpb bundle. For Claude Desktop builds that still support local configuration, use the following JSON stdio configuration as a fallback:
{"mcpServers":{"google-crux":{"command":"npx","args":["-y","mcp-google-crux@latest"],"env":{"CRUX_API_KEY":"your_key"}}}}
In those builds, save it to ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows.
Cursor
Add {"mcpServers":{"google-crux":{"type":"stdio","command":"npx","args":["-y","mcp-google-crux@latest"],"env":{"CRUX_API_KEY":"your_key"}}}} to ~/.cursor/mcp.json on macOS/Linux or %USERPROFILE%\.cursor\mcp.json on Windows. Cursor MCP documentation
VS Code
Run MCP: Open User Configuration and add:
{"servers":{"google-crux":{"type":"stdio","command":"npx","args":["-y","mcp-google-crux@latest"],"env":{"CRUX_API_KEY":"${input:crux_api_key}"}}},"inputs":[{"type":"promptString","id":"crux_api_key","description":"Google Cloud API key","password":true}]}
Check it with MCP: List Servers. VS Code MCP documentation
What you can ask it to do
- Does this public origin or URL pass Core Web Vitals?
- Compare phone, desktop, tablet and all-device results.
- Is this page faster or slower than the site average?
- How did LCP, INP and CLS change during the last 25 weeks?
- Show the raw CrUX histograms and percentiles for a technical review.
How to read CrUX data
CrUX reports a rolling 28-day window, updated daily. Historical data is weekly and updates on Mondays. The key value is p75: 75% of observed visits are at or below it. get_core_web_vitals interprets metric thresholds for you; raw record tools expose full histograms and density fractions.
No data does not mean the site is broken. It means Google has no sufficiently large public Chrome-user sample for that origin, URL or device group. Tablets and individual URLs often have no data.
Getting access
- In Google Cloud Console, create or select a project; no billing account is needed for CrUX.
- Enable the Chrome UX Report API.
- Create an API key in APIs & Services → Credentials.
- Restrict the key to Chrome UX Report API and pass it as
CRUX_API_KEY.
The key is stored in the MCP client configuration and is sent in the API request URL, so treat it as a password.
Configuration
| Variable | Required | Description |
|---|---|---|
CRUX_API_KEY | Yes | Google Cloud key with Chrome UX Report API enabled. |
CRUX_API_BASE | No | API base URL override. |
CRUX_TIMEOUT_MS | No | Per-request timeout; default 30000 ms. |
CRUX_MAX_RETRIES | No | Retries for 429, 5xx and network failures; default 3. |
Data, limits and background work
- Read-only public dataset. The server cannot alter sites, Search Console, CrUX records or Google rankings.
- Quota-aware retries. It retries
429, 5xx and network errors with backoff. Keep compound comparisons in mind when budgeting the 150 queries per minute project quota. - No background monitoring. The server works only while called. If your AI app supports scheduled tasks, it can create a recurring performance report.
- Anonymous telemetry. It sends installation and version data plus tool names, never API keys, queried URLs, results, arguments or prompts. Set
ASKADS_TELEMETRY=0to opt out.
Technical documentation
- MCP capability catalog — task-oriented pages for every tool.
- All tools and inputs
- Development documentation
- Publishing documentation
- CrUX API documentation
Support
Found a bug or need a scenario? Create an issue or write in Telegram.
Installation
Source-derived launch command. Check the maintainer’s required arguments and credentials before running:
npx -y mcp-google-cruxSet up in your AI client
Merge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.
{
"mcpServers": {
"io-github-a1-x-tech-mcp-google-crux": {
"command": "npx",
"args": [
"-y",
"mcp-google-crux"
]
}
}
}Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.
Claude Desktop setup referencePackage
Compatible MCP Clients
Google CrUX MCP works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.
- Claude Desktop
~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect. - Cursor
~/.cursor/mcp.jsonRestart Cursor for changes to take effect. - VS Code
.vscode/mcp.jsonReload VS Code window for changes to take effect. - Windsurf
~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect. - Claude Code
.mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.