@pulspeed/mcp-server

Website performance monitoring for AI agents.

Pulspeed MCP server exposes 10 tools for scanning sites, reading Core Web Vitals, detecting regressions, and getting AI-powered recommendations — all callable by Claude, Cursor, Windsurf, and any MCP-compatible agent.

Quick Setup

Get an API key

Sign up at pulspeed.ai → Settings → API Tokens → create a token.

Claude Code (CLI)

claude mcp add pulspeed -e PULSPEED_API_KEY=your_token_here -- npx -y @pulspeed/mcp-server

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "pulspeed": {
      "command": "npx",
      "args": ["-y", "@pulspeed/mcp-server"],
      "env": {
        "PULSPEED_API_KEY": "your_token_here"
      }
    }
  }
}

Cursor

Edit .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "pulspeed": {
      "command": "npx",
      "args": ["-y", "@pulspeed/mcp-server"],
      "env": {
        "PULSPEED_API_KEY": "your_token_here"
      }
    }
  }
}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "pulspeed": {
      "command": "npx",
      "args": ["-y", "@pulspeed/mcp-server"],
      "env": {
        "PULSPEED_API_KEY": "your_token_here"
      }
    }
  }
}

Tools

All tools that identify a site accept either url or site_id.

scan_site

Trigger a PageSpeed Insights scan. Creates the site automatically if not yet tracked. Blocks until done (~30–60s) by default.

bulk_scan

Scan multiple URLs at once (max 10). All jobs are dispatched immediately.

list_sites

List all monitored sites with latest scores and scan settings.

get_site_metrics

Core Web Vitals for a site with trend analysis and score history.

get_recommendations

AI-powered optimisation recommendations from the latest scan analysis. Requires Developer or Scale plan.

compare_snapshots

Compare two scans with % deltas and a human-readable assessment (🟢 Significant improvement → 🔴 Significant regression).

list_regressions

Find consecutive scans where the performance score dropped significantly.

get_usage

Current billing-period consumption: scans used/remaining, AI analyses, plan limits.

set_performance_budget

Set metric thresholds for a site. Violations trigger threshold.exceeded webhook events on the next scan.

get_raw_audit

Full Lighthouse audit data for a specific audit key — detailed resource-level breakdown.

Common audit keys: render-blocking-resources, bootup-time, unused-javascript, uses-optimized-images, network-requests, uses-text-compression.

Example Prompts

"Scan https://mysite.com and tell me the performance score"

"What's the LCP trend for mysite.com over the last 30 days?"

"My site slowed down today — what changed?"

"Scan all pages: homepage, /about, /blog and compare their scores"

"Set a performance budget: score ≥ 80, LCP ≤ 2500ms"

"Show me the render-blocking resources slowing down mysite.com"

Example: Diagnose a regression

User: "My Lighthouse score dropped 12 points overnight. What happened?"

→ list_regressions(url="https://mysite.com", threshold=5)
   "🔴 CRITICAL −12 pts: 78 → 66 on 2026-02-22 (snapshot #142)"

→ compare_snapshots(url="https://mysite.com")
   "LCP: 2100ms → 3800ms (+81% ✗)  TBT: 180ms → 520ms (+189% ✗)"

→ get_raw_audit(url="https://mysite.com", audit_key="bootup-time")
   "analytics-v2.js — 1840ms execution. Saves 1.2s if deferred."

Agent: "A new analytics script blocks the main thread for 1.84s,
        causing LCP and TBT to spike. Defer or async-load it."

Environment Variables

Plans

All plans include MCP access. Quotas apply:

Development

git clone https://github.com/pulspeed/mcp-server
cd mcp-server
npm install
npm run build    # compile TypeScript → dist/
npm run dev      # watch mode
npm start        # run compiled server

License

MIT © Pulspeed