kubestash-mcp

An MCP server for inspecting KubeStash backup health on any Kubernetes cluster. It connects through your kubeconfig — exactly like kubectl — and exposes read-only tools that an AI assistant (Claude Code, Claude Desktop, etc.) can call in natural language.

Its headline capability is stuck-repository detection: KubeStash's Repository.status.lastBackupTime can freeze while backups keep succeeding, which silently breaks any alert that reads that field. This server computes the true backup freshness from status.recentSnapshots and tells you when the two disagree.

No vendor lock-in: no hardcoded endpoints, clusters, metrics backend, or auth. If kubectl can reach your cluster, so can this.

Install

# run straight from PyPI, no install
uvx mcp-server-kubestash

# or install into a tool environment
uv tool install mcp-server-kubestash

Requires Python 3.11+ and a kubeconfig with access to the KubeStash CRDs (core.kubestash.com, storage.kubestash.com).

Configure an MCP client

Add to your MCP client config (e.g. ~/.mcp.json):

{
  "mcpServers": {
    "kubestash": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-kubestash"],
      "env": {
        "KUBESTASH_CONTEXTS": "all",
        "KUBESTASH_STALE_HOURS": "24"
      }
    }
  }
}

All settings are optional — see .env.example:

Tools

All tools are read-only — the server never mutates cluster state.

How "stuck" is determined

For each Repository, the server compares status.lastBackupTime against the newest status.recentSnapshots[].snapshotTime whose phase == "Succeeded". If the newest succeeded snapshot is more than KUBESTASH_STUCK_THRESHOLD_MINUTES newer than lastBackupTime — or snapshots exist but lastBackupTime is unset — the repository is stuck: backups are healthy, but the status field (and anything alerting on it) is not.

Development

uv sync --all-extras --dev
uv run ruff check .
uv run pytest -q

The suite is fully offline (the Kubernetes client is mocked). A small opt-in end-to-end check runs against a real cluster when RUN_E2E=1 and a kubeconfig are present.

License

MIT