agent-pulse-mcp

Agent-native host monitoring MCP server — exposes real-time system vital signs (CPU, Memory, Temperature) to intelligent agents.

Why?

Traditional monitoring tools (iStat Menus, Activity Monitor, htop) are designed for humans. AI Agents need structured, machine-readable access to host metrics so they can:

• Diagnose slow builds ("CPU is at 95%")
• Choose model size based on available memory
• Monitor resource trends over time
• Alert before OOM or thermal throttling

agent-pulse-mcp bridges this gap as a standard Model Context Protocol server.

Features

• 5 MCP Tools — getSystemStatus, getCPUUsage, getMemoryUsage, getTemperature, subscribeMetrics
• Agent-readable output — both human-friendly text and structured JSON
• Built-in warning engine — configurable thresholds for CPU, memory, temperature
• Streaming support — subscribe to periodic metric snapshots
• Dual transport — stdio (CLI/Desktop) and StreamableHTTP (Web/Cloud)
• Read-only & safe — never executes shell commands or modifies system state
• Zero config — works out of the box with sensible defaults

Quick Start

Install

npm install -g agent-pulse-mcp

Use with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "agent-pulse": {
      "command": "agent-pulse-mcp"
    }
  }
}

Use with Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "agent-pulse": {
      "command": "npx",
      "args": ["-y", "agent-pulse-mcp"]
    }
  }
}

HTTP Mode (for Web / Cloud Agents)

# Start the HTTP server (default port 3100)
npx agent-pulse-mcp-sse

# Or with custom port
PORT=8080 npx agent-pulse-mcp-sse

In development, use npm run dev:sse. In production after build, use node dist/sse.js.

Endpoints:

• POST /mcp — MCP JSON-RPC requests (also initializes sessions)
• GET /mcp — SSE stream for server-initiated messages
• DELETE /mcp — Terminate a session
• GET /health — Health check (returns { status, activeSessions })

MCP Tools

getSystemStatus

Returns a complete system snapshot.

── System Status ──
CPU: 42.3% | Load: 3.21, 2.87, 2.54
Memory: 12.4 GB / 16.0 GB (77.5%)
Swap: 1.2 GB / 4.0 GB
Temperature: CPU 62°C | GPU N/A
Top processes:
  1234 node — CPU 12.3%, Mem 4.5%
  5678 chrome — CPU 8.1%, Mem 12.3%

Also returns the full structured JSON:

{
  "cpu": {
    "totalUsage": 42.3,
    "perCore": [38.2, 45.1, 40.8, 44.9],
    "loadAvg": [3.21, 2.87, 2.54],
    "topProcesses": [...]
  },
  "memory": {
    "total": 17179869184,
    "used": 13312344064,
    "free": 3867525120,
    "swapUsed": 1288490188,
    "swapTotal": 4294967296
  },
  "temperature": {
    "cpu": 62,
    "gpu": null
  },
  "warnings": [],
  "timestamp": 1709571234567
}

getCPUUsage

CPU metrics only. Optional topN parameter (1–50, default: 5).

getMemoryUsage

Memory metrics only (total, used, free, swap).

getTemperature

Temperature readings (CPU, GPU). Returns null when sensors are inaccessible.

subscribeMetrics

Collects periodic snapshots for trend analysis.

| Parameter | Type | Default | Description | | ---------- | ------ | ------- | ----------------------------------- | | interval | number | 2000 | Sampling interval in ms (500–60000) | | duration | number | 10000 | Total duration in ms (1000–300000) |

Maximum 30 snapshots per call to prevent excessively long blocking.

Warning Engine

Built-in thresholds generate structured warnings:

| Metric | Warning | Critical | | ------------ | ------- | -------- | | CPU Usage | ≥ 80% | ≥ 90% | | Memory Usage | ≥ 75% | ≥ 85% | | Temperature | ≥ 85°C | ≥ 95°C |

Warnings appear in every snapshot:

{
  "warnings": [
    {
      "metric": "cpu",
      "message": "CPU usage critically high: 95.2% (threshold: 90%)",
      "severity": "critical"
    }
  ]
}

Architecture

┌─────────────┐
│  Collector   │  systeminformation + os module
│  (CPU/Mem/T) │
└──────┬──────┘
       │
┌──────▼──────┐
│    Cache     │  Latest snapshot + ring buffer
│ (30 samples) │
└──────┬──────┘
       │
┌──────▼──────┐
│  Analyzer    │  Rule-based warnings
│ (thresholds) │
└──────┬──────┘
       │
┌──────▼──────┐
│  MCP Server  │  Tools exposed via MCP protocol
│ (stdio/HTTP) │
└─────────────┘

Development

git clone https://github.com/wangcch/agent-pulse-mcp.git
cd agent-pulse-mcp
npm install

# Run in dev mode (stdio)
npm run dev

# Run HTTP server in dev mode
npm run dev:sse

# Build
npm run build

# Test
npm test

# Format
npm run format

# Type check
npm run lint

Roadmap

• v0.1.0 — CPU, Memory, Temperature, 5 MCP tools, dual transport ✅
• v0.2.0 — Ring buffer trend analysis, configurable thresholds via env/args
• v0.3.0 — GPU usage monitoring, Docker container stats

Platform Support

| Platform | CPU | Memory | Temperature | | -------- | --- | ------ | ------------------------- | | macOS | ✅ | ✅ | ⚠️ (requires permissions) | | Linux | ✅ | ✅ | ✅ | | Windows | ✅ | ✅ | ⚠️ (limited) |

License

MIT © wangcch