k8s-pilot

The Central Pilot for Your Kubernetes Fleets ✈️✈️

k8s_pilot is a lightweight, centralized control plane server for managing multiple Kubernetes clusters at once.
With powerful tools and intuitive APIs, you can observe and control all your clusters from one cockpit.

---

🚀 Overview

• 🔄 Supports multi-cluster context switching
• 🔧 Enables CRUD operations on most common Kubernetes resources
• 🔒 Readonly mode for safe cluster inspection
• ⚙️ Powered by MCP for Claude AI and beyond
• 🌐 Streamable HTTP transport support for remote access
• 🤖 MCP Prompts for guided operations
• 📝 Context-aware logging for write operations

---

🧰 Prerequisites

• Python 3.13 or higher
• uv package manager
• Access to Kubernetes clusters (~/.kube/config or in-cluster config)

# Install uv (if not installed)

# For MacOS
brew install uv

# For Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

Installation

# Clone the repository
git clone https://github.com/bourbonkk/k8s-pilot.git
cd k8s-pilot

# Launch with uv + MCP
uv run --with "mcp[cli]>=1.28.0,<2" python k8s_pilot.py

🆕 What's New in v2.0

• Streamable HTTP Transport: Remote cluster management via HTTP (in addition to stdio)
• MCP Prompts: Built-in prompt templates for common K8s operations
• Context-aware Logging: Write operations now report progress via MCP context
• Bug Fixes: Fixed missing API clients for Ingress and RBAC resources
• Security: Added readonly checks for node modification operations
• Dockerfile: Modernized with uv package manager for faster builds

Usage

Normal Mode (Full Access)

# Start with full read/write access
uv run --with "mcp[cli]>=1.28.0,<2" python k8s_pilot.py

Readonly Mode (Safe Inspection)

# Start in readonly mode - only read operations allowed
uv run --with "mcp[cli]>=1.28.0,<2" python k8s_pilot.py --readonly

Streamable HTTP Mode (Remote Access)

# Start with Streamable HTTP transport for remote access
uv run --with "mcp[cli]>=1.28.0,<2" python k8s_pilot.py --transport streamable-http

Command Line Options

# Show help
uv run --with "mcp[cli]>=1.28.0,<2" python k8s_pilot.py --help

Run via Docker

You can run k8s-pilot directly using the published Docker image without installing uv locally. Make sure to mount your ~/.kube/config so the container can access your clusters.

docker run -i --rm \
  -v ~/.kube/config:/root/.kube/config \
  ghcr.io/bourbonkk/k8s-pilot:latest

Readonly Mode

The --readonly flag enables a safety mode that prevents any write operations to your Kubernetes clusters. This is perfect for:

• Cluster inspection without risk of accidental changes
• Audit scenarios where you need to view but not modify
• Learning environments where you want to explore safely
• Production monitoring with zero risk of modifications

Protected Operations (Blocked in Readonly Mode)

• pod_create, pod_update, pod_delete
• deployment_create, deployment_update, deployment_delete
• service_create, service_update, service_delete
• configmap_create, configmap_update, configmap_delete
• secret_create, secret_update, secret_delete
• namespace_create, namespace_delete
• All other create/update/delete operations

Allowed Operations (Always Available)

• pod_list, pod_detail, pod_logs
• deployment_list, deployment_get
• service_list, service_get
• configmap_list, configmap_get
• secret_list, secret_get
• namespace_list, namespace_get
• All other list/get operations

MCP Prompts

k8s-pilot includes built-in prompt templates for common operations:

Prompt	Description
troubleshoot_pod	Step-by-step pod troubleshooting guide
deployment_guide	Guided application deployment workflow
cluster_health_check	Comprehensive cluster health assessment
namespace_cleanup	Safe namespace cleanup procedure

Usage with Claude Desktop

Use this config to run k8s_pilot MCP server from within Claude:

{
  "mcpServers": {
    "k8s_pilot": {
      "command": "uv",
      "args": [
        "--directory",
        "<path-to-cloned-repo>/k8s-pilot",
        "run",
        "--with",
        "mcp[cli]>=1.28.0,<2",
        "python",
        "k8s_pilot.py"
      ]
    }
  }
}

For readonly mode, use this configuration:

{
  "mcpServers": {
    "k8s_pilot_readonly": {
      "command": "uv",
      "args": [
        "--directory",
        "<path-to-cloned-repo>/k8s-pilot",
        "run",
        "--with",
        "mcp[cli]>=1.28.0,<2",
        "python",
        "k8s_pilot.py",
        "--readonly"
      ]
    }
  }
}

For Docker, use this configuration (replace YOUR_USERNAME with your actual Mac user name):

{
  "mcpServers": {
    "k8s_pilot_docker": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/Users/YOUR_USERNAME/.kube/config:/root/.kube/config",
        "ghcr.io/bourbonkk/k8s-pilot:latest"
      ]
    }
  }
}

Replace <path-to-cloned-repo> with the actual directory where you cloned the repo.

Scenario

Create a Deployment using the nginx:latest image in the pypy namespace, and also create a Service that connects to it.

Key Features

Multi-Cluster Management

• Seamlessly interact with multiple Kubernetes clusters
• Perform context-aware operations
• Easily switch between clusters via MCP prompts

Resource Control

• View, create, update, delete:
  • Deployments, Services, Pods
  • ConfigMaps, Secrets, Ingresses
  • StatefulSets, DaemonSets
  • Roles, ClusterRoles
  • PersistentVolumes & Claims

Namespace Operations

• Create/delete namespaces
• List all resources in a namespace
• Manage labels and resource quotas

Node Management

• View node details and conditions
• Cordon/uncordon, label/taint nodes
• List pods per node

License

This project is licensed under the MIT License. See the LICENSE file for details.