# Stack Guardian

> Stack Guardian is an MCP server for developer tools. Health checks for a home AI stack: Ollama nodes, NVIDIA GPUs and tailnet peers. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Platforms:** CLI, Linux, macOS, Windows, self-hosted
- **Repository:** https://github.com/luminarisoftwares/stack-guardian
- **MCP Registry name:** io.github.LuminariSoftwares/stack-guardian
- **Categories:** [developer tools](https://ai-powered.com/categories/developer-tools), [AI models and LLM tooling](https://ai-powered.com/categories/ai-and-llm)
- **Listing updated:** 2026-11-15

## About

Instead of guessing why a model is slow on a multi-machine local setup, it collects a snapshot of your nodes (Ollama or OpenAI-compatible endpoints, loaded models, NVIDIA GPUs on the local machine, tailnet peers) and runs 14 small Python rules against it. Findings carry a severity, evidence and a confidence grade: one run is at most LIKELY and the same finding on a second run becomes VERIFIED. Typical findings include an unreachable Ollama endpoint, an offline tailnet peer or a model about to unload.

It ships as a CLI whose doctor command exits 0, 1 or 2, a read-only MCP stdio server, a small HTTP endpoint with Prometheus metrics and a DeepSeek Harness plugin. A finding may offer a typed fix that you run on purpose; fixes are dry runs unless --apply is passed. It uses only the standard library on Python 3.11+, and is not affiliated with the StackGuardian company.

## Features

- **Fourteen checks:** Rules covering endpoints, models, GPUs and peers.
- **Confidence grades:** LIKELY after one run, VERIFIED when seen twice.
- **Exit codes:** The doctor command exits 0, 1 or 2.
- **Read-only MCP:** The MCP server never records state.
- **Prometheus metrics:** An HTTP endpoint serves a snapshot and metrics.
- **Dry-run fixes:** Fixes apply only with --apply and leave an audit line.

## Good for

- Find why a local model is slow
- Detect an offline tailnet node
- Warn when a loaded model is about to unload
- Export stack health to Prometheus

## Install

### Claude Code (Terminal)

```sh
claude mcp add stack-guardian --env STACK_GUARDIAN_NODES='<STACK_GUARDIAN_NODES>' -- uvx stack-guardian
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "stack-guardian": {
      "command": "uvx",
      "args": [
        "stack-guardian"
      ],
      "env": {
        "STACK_GUARDIAN_NODES": "<STACK_GUARDIAN_NODES>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "stack-guardian": {
      "command": "uvx",
      "args": [
        "stack-guardian"
      ],
      "env": {
        "STACK_GUARDIAN_NODES": "<STACK_GUARDIAN_NODES>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "stack-guardian": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "stack-guardian"
      ],
      "env": {
        "STACK_GUARDIAN_NODES": "<STACK_GUARDIAN_NODES>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "stack-guardian": {
      "command": "uvx",
      "args": [
        "stack-guardian"
      ],
      "env": {
        "STACK_GUARDIAN_NODES": "<STACK_GUARDIAN_NODES>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "stack-guardian": {
      "command": "uvx",
      "args": [
        "stack-guardian"
      ],
      "env": {
        "STACK_GUARDIAN_NODES": "<STACK_GUARDIAN_NODES>"
      }
    }
  }
}
```

## FAQ

### What does it need?

Python 3.11 or newer and no runtime dependencies.

### Does it support AMD GPUs?

The README says NVIDIA only, and only on the machine running it.

### Can I try it without a stack?

Yes, run doctor against the example snapshot, which exits 2 on purpose.

### Does it fix things automatically?

No, fixes run only when you request them.

### How do I add Stack Guardian to Claude Code?

Run this command in your terminal: claude mcp add stack-guardian --env STACK_GUARDIAN_NODES='<STACK_GUARDIAN_NODES>' -- uvx stack-guardian

### What are the best alternatives to Stack Guardian?

The closest alternatives to Stack Guardian are Guard, Stalemodel, AIOps Field Notes, LLM Preflight and Paw Pulse.

## Where this comes from

- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [Guard](https://ai-powered.com/mcp/guard): Guard is an open-source MCP server for developer tools.
- [Stalemodel](https://ai-powered.com/mcp/stalemodel): Stalemodel is an open-source MCP server for ai models and llm tooling.
- [AIOps Field Notes](https://ai-powered.com/mcp/aiops-field-notes): AIOps Field Notes is an open-source MCP server for knowledge and memory.
- [LLM Preflight](https://ai-powered.com/mcp/llm-preflight): LLM Preflight is an MCP server for ai models and llm tooling.
- [Paw Pulse](https://ai-powered.com/mcp/paw-pulse): Paw Pulse is a free MCP server for ai models and llm tooling.
- [AI Guard](https://ai-powered.com/mcp/ai-guard): AI Guard is an open-source MCP server for developer tools.
- [Budgethelm](https://ai-powered.com/mcp/budgethelm): Budgethelm is a freemium MCP server for developer tools.
- [AI Host Optimizer](https://ai-powered.com/mcp/ai-host-optimizer): AI Host Optimizer is an open-source MCP server for ai models and llm tooling.

---
Source: https://ai-powered.com/mcp/stack-guardian
