local-vitals-mcp

Hardware and environment guardrail MCP server for AI coding agents (Cursor, Claude Code, Cline) to prevent runaway local resource exhaustion, locked ports, and zombie background processes.

⚡ Why local-vitals-mcp?

When AI coding agents execute builds, spin up background headless browsers, run large test suites, or spawn local LLM workers, they often run into local host bottlenecks:

1. Port Collisions (EADDRINUSE): A previous server didn't shut down, causing dev server commands to fail in endless loops.

2. Zombie Background Processes: Stale headless Playwright/Puppeteer browsers and dangling test workers eat gigabytes of RAM.

3. Hardware Exhaustion: Spawning heavy tasks when RAM > 85% or CPU > 90% locks the user's host machine.

4. VRAM OOM Errors: Loading local embeddings or vision models without checking available GPU VRAM causes hard CUDA crashes.

local-vitals-mcp gives the agent autonomous awareness of host hardware constraints and the tools to safely resolve them.

Related MCP server: open-monitor

🚀 Quick Setup

1. Cursor IDE (.cursor/mcp.json)

Add the following block to your project's .cursor/mcp.json or global Cursor settings:

{
  "mcpServers": {
    "local-vitals": {
      "command": "npx",
      "args": ["-y", "local-vitals-mcp"]
    }
  }
}

2. Claude Desktop (claude_desktop_config.json)

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "local-vitals": {
      "command": "npx",
      "args": ["-y", "local-vitals-mcp"]
    }
  }
}

3. Cline (VS Code Extension)

In Cline Settings > MCP Servers, add:

• Server Name: local-vitals

• Command: npx

• Args: ["-y", "local-vitals-mcp"]

🛠️ Implemented MCP Tools

💬 Natural Prompt Triggers for Agents

Here are examples of how your AI coding agent uses these tools automatically:

• "My dev server failed with Error: listen EADDRINUSE: address already in use :::3000. Please free the port and restart."
  👉 Agent calls kill_port_process(3000) and re-runs npm run dev.

• "Before we start running this test suite, check if the machine has enough free memory and CPU headroom."
  👉 Agent calls get_system_vitals to verify threshold parameters.

• "Do I have enough free VRAM to run a local 7B quantization model?"
  👉 Agent calls get_gpu_vram and inspects freeVramMB.

• "My computer feels slow after running multiple test runs. Clean up any leftover browser sessions."
  👉 Agent calls clean_orphan_processes(dryRun: false).

🛡️ Built-in Safety Guardrails

• Stdio Protocol Isolation: All debug and informational logs are strictly routed to stderr. stdout is exclusively reserved for JSON-RPC messages to guarantee zero transport corruption.

• Protected System PIDs: Refuses to kill system kernel processes (PID <= 4, Windows System/Idle, Unix init/launchd).

• Self-Preservation: Prevents suicide termination if the target PID is the MCP server process itself or its parent runner.

• Graceful Fallbacks: If nvidia-smi or sensors are unavailable, tools return structured diagnostic JSON without crashing the server.

💻 Development & Local Testing

# Clone repository
git clone https://github.com/Optimus-Prime-Blip/local-vitals-mcp.git
cd local-vitals-mcp

# Install dependencies
npm install

# Compile TypeScript
npm run build

# Run MCP server locally over stdio
npm start

📄 License

MIT © Arnav Yadav