{"id":51301545,"url":"https://github.com/teles/web-performance-mcp","last_synced_at":"2026-06-30T20:02:25.928Z","repository":{"id":364586387,"uuid":"1268471156","full_name":"teles/web-performance-mcp","owner":"teles","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-13T15:50:49.000Z","size":46,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-13T17:22:52.294Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/teles.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-13T15:15:54.000Z","updated_at":"2026-06-13T15:50:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/teles/web-performance-mcp","commit_stats":null,"previous_names":["teles/web-performance-mcp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/teles/web-performance-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teles%2Fweb-performance-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teles%2Fweb-performance-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teles%2Fweb-performance-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teles%2Fweb-performance-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/teles","download_url":"https://codeload.github.com/teles/web-performance-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teles%2Fweb-performance-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34981391,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-30T02:00:05.919Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-30T20:02:21.031Z","updated_at":"2026-06-30T20:02:25.921Z","avatar_url":"https://github.com/teles.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# web-performance-mcp\n\nMCP server for compact web performance analysis with the official Google APIs:\n\n- PageSpeed Insights API v5\n- Chrome UX Report API\n\nIt does not run Lighthouse locally and does not use Puppeteer, Playwright, Chrome DevTools Protocol, or a local browser.\n\n## Quick Start With npx\n\nAfter the package is published to npm:\n\n```bash\nnpx -y web-performance-mcp\n```\n\nThe server reads `GOOGLE_API_KEY` from the environment. It also loads a `.env` file from the current working directory, so MCP clients can keep secrets in the project they are analyzing.\n\nCreate `.env` in your project:\n\n```bash\nGOOGLE_API_KEY=your-google-api-key-here\n```\n\n## Codex MCP Configuration\n\nUse `npx` directly:\n\n```toml\n[mcp_servers.webPerformance]\ncommand = \"npx\"\nargs = [\"-y\", \"web-performance-mcp\"]\ncwd = \"/path/to/project-with-env\"\nstartup_timeout_sec = 30\ntool_timeout_sec = 180\n```\n\n`cwd` should point to the project that contains `.env`.\n\nYou can also pass the key through MCP env config:\n\n```toml\n[mcp_servers.webPerformance.env]\nGOOGLE_API_KEY = \"your-google-api-key-here\"\n```\n\nPrefer `.env` or shell environment variables for local use so secrets do not end up in shared config.\n\n## Required Google APIs\n\nCreate a Google Cloud API key and enable:\n\n- PageSpeed Insights API\n- Chrome UX Report API\n\nRestrict the API key to only these APIs.\n\n## Tools\n\n### `analyze_pagespeed`\n\nAnalyze one URL with PageSpeed Insights.\n\n```json\n{\n  \"url\": \"https://www.example.com/\",\n  \"strategy\": \"mobile\",\n  \"categories\": [\"performance\"]\n}\n```\n\nReturns:\n\n- performance score;\n- lab metrics: FCP, LCP, Speed Index, TBT, CLS, TTI, TTFB;\n- high-impact audits;\n- compact diagnostics for render-blocking resources, unused JS/CSS, image optimization, and main-thread work;\n- recommendations.\n\n### `analyze_pagespeed_batch`\n\nAnalyze up to 10 URLs with concurrency control.\n\n```json\n{\n  \"urls\": [\n    \"https://www.example.com/\",\n    \"https://www.example.com/blog/\"\n  ],\n  \"strategy\": \"mobile\",\n  \"categories\": [\"performance\"],\n  \"concurrency\": 2\n}\n```\n\n### `get_crux_url`\n\nQuery Chrome UX Report data for a URL.\n\n```json\n{\n  \"url\": \"https://www.example.com/\"\n}\n```\n\nReturns LCP, INP, CLS p75 and good/needs improvement/poor distributions when CrUX has enough real-user data.\n\n### `get_crux_origin`\n\nQuery Chrome UX Report data for an origin.\n\n```json\n{\n  \"origin\": \"https://www.example.com\"\n}\n```\n\n### `compare_web_performance`\n\nCombine PageSpeed and CrUX for several URLs and prioritize likely problems.\n\n```json\n{\n  \"urls\": [\n    \"https://www.example.com/\",\n    \"https://www.example.com/blog/\"\n  ],\n  \"strategy\": \"mobile\",\n  \"categories\": [\"performance\"],\n  \"concurrency\": 2\n}\n```\n\n## Response Shape\n\nResponses are intentionally compact. The server does not send the raw PageSpeed or CrUX API payload back to the model.\n\nCrUX tools return `available: false` when Google has no field data for the URL or origin.\n\nAPI errors are returned as compact MCP errors for timeout, quota, permissions, invalid URLs, and incomplete API responses.\n\n## Local Development\n\n```bash\ncorepack enable\npnpm install\ncp .env.example .env\npnpm build\npnpm test\npnpm start\n```\n\nUse the local checkout in Codex:\n\n```toml\n[mcp_servers.webPerformance]\ncommand = \"node\"\nargs = [\"/Users/teles/dev/web-performance-mcp/dist/index.js\"]\ncwd = \"/path/to/project-with-env\"\nstartup_timeout_sec = 30\ntool_timeout_sec = 180\n```\n\n## Publishing to npm\n\nThe npm package name is:\n\n```text\nweb-performance-mcp\n```\n\nThe name is currently available if `npm view web-performance-mcp` returns `404 Not Found`. During `npm publish`, however, a `404 Not Found` usually means the workflow cannot create or access that package name with the current npm authentication.\n\n### One-Time npm Setup\n\n1. Create or log in to your npm account.\n2. Publish the package once with an npm account that can create unscoped public packages, or configure npm Trusted Publishing for the GitHub repository before the automated release runs.\n3. For Trusted Publishing, configure this package on npmjs.com with:\n\n```text\nProvider: GitHub Actions\nOrganization or user: teles\nRepository: web-performance-mcp\nWorkflow filename: release.yml\nAllowed action: npm publish\n```\n\n4. Keep the GitHub Actions workflow permissions:\n\n```yaml\npermissions:\n  contents: write\n  id-token: write\n```\n\nTrusted Publishing requires npm CLI 11.5.1+ and Node.js 22.14.0+. The release workflow uses Node 24.\n\nIf the release workflow fails while publishing with `npm error 404 Not Found - PUT https://registry.npmjs.org/web-performance-mcp`, confirm that the package exists under your npm account or that Trusted Publishing is configured for exactly `teles/web-performance-mcp` and workflow filename `release.yml`.\n\n### Release Flow\n\nThis repository uses `zero-release`.\n\nCommits should follow Conventional Commits:\n\n```text\nfeat: add new tool\nfix: handle CrUX permission errors\ndocs: improve npx setup\n```\n\nPreview the next release locally:\n\n```bash\npnpm release:dry-run\n```\n\nCheck release readiness:\n\n```bash\npnpm release:doctor\n```\n\nPush to `main` to publish:\n\n```bash\ngit push origin main\n```\n\nThe workflow runs tests, builds the package, updates `CHANGELOG.md` and `package.json`, creates a GitHub release, and publishes to npm with the `npm` plugin.\n\n### Manual Publish Fallback\n\nIf you do not want to use Trusted Publishing yet:\n\n```bash\ncorepack enable\npnpm install --frozen-lockfile\npnpm test\npnpm build\nnpm login\nnpm publish --access public\n```\n\nUse zero-release for normal releases once npm Trusted Publishing is configured.\n\n## Security\n\n- Never commit `.env` or real credentials.\n- Restrict `GOOGLE_API_KEY` to PageSpeed Insights API and Chrome UX Report API.\n- The API key is never printed by the server.\n- The server does not execute browser automation.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fteles%2Fweb-performance-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fteles%2Fweb-performance-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fteles%2Fweb-performance-mcp/lists"}