@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