@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.

| Param | Type | Required | Description | |-------|------|----------|-------------| | url | string | ✓ | URL to scan | | strategy | mobile | desktop | — | Default: mobile | | wait | boolean | — | true (default) = wait for result; false = async, returns job_id |

bulk_scan

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

| Param | Type | Required | Description | |-------|------|----------|-------------| | urls | string[] | ✓ | 1–10 URLs | | strategy | mobile | desktop | — | Default: mobile | | wait | boolean | — | false (default) = async; true = sequential with results |

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.

| Param | Type | Required | Description | |-------|------|----------|-------------| | url | string | ✓ or site_id | Site URL | | site_id | number | ✓ or url | Pulspeed site ID | | period | 24h | 7d | 30d | 90d | — | History window (default: 7d) |

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).

| Param | Type | Description | |-------|------|-------------| | url / site_id | — | Site identifier (compares latest two) | | snapshot_id_a | number | Specific newer snapshot | | snapshot_id_b | number | Specific older snapshot |

list_regressions

Find consecutive scans where the performance score dropped significantly.

| Param | Type | Description | |-------|------|-------------| | url / site_id | — | Site identifier | | threshold | number | Min score drop to count (default: 3) | | limit | number | Scan history to analyse (default: 20, max: 50) |

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.

| Param | Type | Description | |-------|------|-------------| | url / site_id | — | Site identifier | | performance_score | { min: number } | e.g. { min: 80 } | | lcp | { max: number } | Max LCP in ms, e.g. { max: 2500 } | | fcp | { max: number } | Max FCP in ms | | tbt | { max: number } | Max TBT in ms | | ttfb | { max: number } | Max TTFB in ms | | cls | { max: number } | Max CLS, e.g. { max: 0.1 } |

get_raw_audit

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

| Param | Type | Required | Description | |-------|------|----------|-------------| | url / site_id | — | ✓ or snapshot_id | Site identifier | | snapshot_id | number | — | Specific snapshot (default: latest) | | audit_key | string | ✓ | Lighthouse audit key |

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

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | PULSPEED_API_KEY | ✓ | — | API token from pulspeed.ai/settings | | PULSPEED_BASE_URL | — | https://pulspeed.ai/api/v1 | Override for self-hosted |

Plans

All plans include MCP access. Quotas apply:

| Plan | Scans/month | AI Analysis | Webhooks | |------|-------------|-------------|----------| | Free | 30 | 5/month | — | | Developer ($29) | 500 | Included | 5 endpoints | | Scale ($79) | 2,000 | Included | 20 endpoints |

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