Velero MCP Server

The Velero MCP Server is an open-source Model Context Protocol (MCP) server that exposes read-only, safe, structured access to Velero backup and schedule resources running inside any Kubernetes cluster.

It allows AI agents (ChatGPT, Claude, Cursor, GitHub Copilot, etc.) to:

🔍 Inspect Velero backups
🔄 Inspect Velero schedules
📄 Generate Velero Backup YAML manifests
🧩 Access Velero data as MCP resources
🔐 Safely interact with your cluster in read-only mode

This project helps platform engineers automate workflows using AI while ensuring zero-risk, low-privilege, and read-only access to critical cluster configuration.

⭐ Why This Project Exists

Velero is commonly used for:

Kubernetes namespace & cluster backups
Disaster recovery
Cluster migrations
Persistent volume snapshot management

But until now, no MCP server existed to expose Velero CRDs to LLM-based tools in a safe, structured way.

This project provides:

A consistent API for querying Velero
Strong typed models
Complete read-only safety
Guaranteed LLM-friendly output
Ready integration with GitOps

🚀 Features

🔧 MCP Tools

`list_velero_backups(namespace?: str)`

Returns a list of Velero Backup CRs.

`get_velero_backup(name: str, namespace?: str)`

Returns a detailed structured backup object.

`list_velero_schedules(namespace?: str)`

Lists Velero Schedule CRs including cron, paused state, and last backup.

`generate_velero_backup_yaml(...)`

Generates read-only YAML for a Velero Backup.

📦 MCP Resource Endpoints

Resource	Description
`velero://backups`	All backups in default namespace
`velero://schedules`	All schedules in default namespace

These allow LLMs to explore Velero state without calling tools.

🏗 Architecture

Python 3.10+
MCP (official Model Context Protocol SDK)
Kubernetes Python Client
Pydantic models
Safe, read-only design
No kubectl, no exec, no side effects

Flow:

MCP Client → Velero MCP Server → Kubernetes API → Velero CRDs

🔐 Security Model

Designed to be 100% safe

The server never:

Creates backups
Runs restores
Deletes backup objects
Writes anything to Kubernetes

Only reads CRDs via the Kubernetes API.

RBAC Required:

get, list on:
- backups.velero.io
- schedules.velero.io

📥 Installation

git clone https://github.com/YOUR-ORG/velero-mcp-server.git
cd velero-mcp-server

python -m venv .venv
source .venv/bin/activate    # Windows: .venv\Scripts\activate

pip install -r requirements.txt
pip install .

For development:

pip install ".[dev]"

⚙️ Configuration

Environment Variables

Variable	Description	Default
`KUBECONFIG`	Path to kubeconfig	auto
`VELERO_NAMESPACE`	Velero namespace	velero

K8s auth order:

In-cluster ServiceAccount
$KUBECONFIG
~/.kube/config

▶️ Running the Server

Start the server in stdio mode (required by MCP):

python -m velero_mcp_server.server

🧩 Example MCP Client Configuration

ChatGPT MCP configuration

{
  "mcpServers": {
    "velero-mcp": {
      "command": "python",
      "args": ["-m", "velero_mcp_server.server"],
      "env": {
        "KUBECONFIG": "/path/to/kubeconfig",
        "VELERO_NAMESPACE": "velero"
      }
    }
  }
}

Claude Desktop

"mcpServers": {
  "velero-mcp": {
    "command": "python",
    "args": ["-m", "velero_mcp_server.server"],
    "env": {
      "KUBECONFIG": "/path/to/kubeconfig",
      "VELERO_NAMESPACE": "velero"
    }
  }
}

🧪 Example Usage (AI Agent)

List failed backups

“Call list_velero_backups and filter phase = Failed.”

Inspect a backup

“Use get_velero_backup for prod-full and tell me included namespaces.”

Generate a manifest

“Generate a Velero backup YAML including namespaces db, logging, TTL=168h.”

Produces:

apiVersion: velero.io/v1
kind: Backup
metadata:
  name: prod-backup
  namespace: velero
spec:
  includedNamespaces:
    - db
    - logging
  ttl: 168h

🛠 Development

Run linters:

ruff check velero_mcp_server

Type-check:

mypy velero_mcp_server

Run tests:

pytest

🤝 Contributing

We welcome contributions of all kinds:

Add Velero Restore / VolumeSnapshot support
Improve error handling
Add more MCP resources
Add a Helm chart
Add logging or metrics
Improve documentation

Read the full CONTRIBUTING.md.

📜 License

This project is licensed under the MIT License, allowing:

Commercial use
Private use
Modification
Distribution

🗺 Roadmap

Planned improvements:

Add support for Restore CRDs
Snapshot objects
Restore impact analysis
Write-enabled mode (behind strict flags)
Publish to PyPI
Helm chart for cluster deployment

If you'd like to help shape the direction, please open an issue!

velero-mcp