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

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

K8s auth order:

1. In-cluster ServiceAccount

2. $KUBECONFIG

3. ~/.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!