MCP-K8sWizard

The Kubernetes Wizard for Modern DevOps
Streamline your Kubernetes operations with AI-powered natural language interfaces and comprehensive DevOps automation.

🚀 Overview

MCP-K8sWizard is a comprehensive Model Context Protocol (MCP) solution designed for professional DevOps teams. It provides natural language interfaces for complex Kubernetes workflows, enabling teams to manage clusters, monitor applications, and execute operational tasks efficiently through AI-powered conversations.

✨ Key Features

🎯 Multi-Cloud Kubernetes Management

Universal Compatibility: Native support for EKS, AKS, GKE, RKE2, K3s, and standard Kubernetes distributions
Intelligent Cluster Detection: Automatic identification and configuration of cluster types and capabilities
Advanced Resource Management: Comprehensive CRUD operations across all Kubernetes resource types
Real-time Monitoring: Live cluster health, resource utilization, and performance metrics

🤖 AI-Powered Operations

Natural Language Processing: Conversational interface for complex DevOps operations
Intelligent Troubleshooting: AI-driven diagnostics and step-by-step resolution guidance
Smart Prompts: Context-aware prompt suggestions for different scenarios
Automated Insights: Proactive identification of potential issues and optimization opportunities

🔒 Security & Access Control

RBAC Integration: Full integration with Kubernetes RBAC and identity providers
Audit Logging: Comprehensive audit trails for all operations and access
Secure Communication: TLS encryption for all communications
Minimal Privilege: Secure by design with least privilege access patterns

🏗️ Architecture

MCP Protocol Integration

The following diagram shows how MCP-K8sWizard integrates with VSCode/Cursor AI through the Model Context Protocol:

┌─────────────┐    ┌──────────────┐    ┌─────────────────┐
│ Cursor AI   │───▶│ MCP Protocol │───▶│ MCP-K8sWizard   │
└─────────────┘    └──────────────┘    │    Server       │
                                       └─────────┬───────┘
                                                 │
                    ┌────────────────────────────┼────────────────────────────┐
                    │                            │                            │
            ┌───────▼───────┐            ┌───────▼───────┐            ┌───────▼───────┐
            │ Kubernetes    │            │ Context       │            │ Tool Handlers │
            │ API           │            │ Manager       │            │               │
            └───────┬───────┘            └───────┬───────┘            └───────┬───────┘
                    │                            │                            │  
                    ┌────────────────────────────┼────────────────────────────┐
                    │                            │                            │
            ┌───────▼───────┐            ┌───────▼───────┐            ┌───────▼───────┐
            │ K8s Tools     │            │ Kubectl Tools │            │ Prompt Tools  │
            │               │            │               │            │               │
            │ • Cluster Info│            │ • Resource    │            │ • Diagnostics │
            │ • Resources   │            │   CRUD        │            │ • Troubleshoot│
            │ • Logs/Events │            │ • Scaling     │            │ • Optimization│
            │ • Pod Exec    │            │ • Rollouts    │            │ • Security    │
            └───────────────┘            └───────────────┘            └───────────────┘

Component Architecture

The internal architecture of MCP-K8sWizard follows a layered approach:

┌─────────────────────────────────────────────────────────────────────────────┐
│                              MCP Layer                                      │
├─────────────────────────────────────────────────────────────────────────────┤
│  MCP Server  ──▶  Tool Registry  ──▶  Request Router                        │
└──────────────────────────────────┬──────────────────────────────────────────┘
                                   │
┌──────────────────────────────────▼──────────────────────────────────────────┐
│                           Core Services                                     │
├─────────────────────────────────────────────────────────────────────────────┤
│  Context Manager  ──▶  K8s Client Manager  ──▶  Resource Handler            │
│         │                       │                        │                  │
│         └───────────────────────┼────────────────────────┘──────────────────┘
│                                 │                                           │
│  Config Manager  ──▶  Event Monitor ──▶ Kubernetes API                      │
└─────────────────────────────────────────────────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────────────┐
│                         Tool Handlers                                       │
├─────────────────────────────────────────────────────────────────────────────┤
│  K8s Tools        │  Kubectl Tools     │  Prompt Tools     │  Context Tools │
│  ─────────        │  ────────────      │  ───────────      │  ────────────  │
│  • Cluster Ops    │  • Resource Mgmt   │  • AI Guidance    │ • Multi-Cluster│
│  • Monitoring     │  • CRUD Ops        │  • Diagnostics    │ • Context Sw.  │
│  • Debugging      │  • Scaling         │  • Optimization   │ • Health Chk   │
└─────────────────────────────────────────────────────────────────────────────┘

🛠️ Available Tools

Kubernetes Management Tools (37 Total)

Category	Tools	Description
Kubernetes Operations (14)	`k8s_cluster_info`, `k8s_check_all_clusters`, `ping`, `k8s_list_resources`, `k8s_get_resource`, `k8s_get_logs`, `k8s_get_events`, `k8s_exec_in_pod`, `k8s_natural_language_query`	Direct Kubernetes API operations, monitoring, and debugging
Kubectl Operations (12)	`kubectl_get`, `kubectl_describe`, `kubectl_create`, `kubectl_apply`, `kubectl_delete`, `kubectl_context`, `kubectl_scale`, `kubectl_patch`, `kubectl_rollout`, `kubectl_generic`, `explain_resource`, `list_api_resources`	Full CRUD operations, scaling, rollouts, and resource management via kubectl
Context Management (4)	`k8s_set_context`, `k8s_get_current_context`, `k8s_list_contexts`, `k8s_clear_context`	Multi-cluster context switching and management
AI-Powered Guidance (7)	`k8s_diagnose`, `k8s_troubleshoot`, `k8s_optimize`, `k8s_security`, `k8s_performance`, `k8s_deployment`, `prompt_suggestions`	Intelligent diagnostic, optimization, and troubleshooting prompts

🚀 Quick Start

Prerequisites

Go 1.25.1 or later
Kubernetes cluster access (kubeconfig configured)
VSCode/Cursor AI with MCP support
macOS or Linux operating system

Installation

For detailed installation instructions, see our comprehensive Installation Manual.

Quick Setup:

Clone and install

git clone https://github.com/your-org/mcp-k8swizard.git
cd mcp-k8swizard
make install

Configure Cursor AI Add to your ~/.cursor/mcp.json:

{
  "mcpServers": {
    "k8s-wizard": {
      "command": "/path/to/mcp-k8swizard",
      "args": ["--verbose"]
    }
  }
}

Restart Cursor AI and start using natural language commands!

📖 Need detailed instructions? Check out our Installation Manual for step-by-step setup, troubleshooting, and advanced configuration options.

Basic Usage

# Check cluster health
"Show me the status of all my Kubernetes clusters"

# List resources
"List all pods in the production namespace"

# Debug issues
"Get logs from the failing pod in the web-app deployment"

# Scale applications
"Scale the frontend deployment to 5 replicas"

# Troubleshoot problems
"Help me diagnose why my pod is stuck in Pending state"

📋 Natural Language Examples

Cluster Management

"Show me all my Kubernetes clusters and their health status"
"Check the resource usage across all nodes in my EKS cluster"
"List all namespaces and their resource quotas"

Resource Operations

"Create a new namespace called 'staging'"
"List all deployments with more than 3 replicas"
"Show me the configuration of the nginx service"
"Delete all pods with the label 'app=test'"

Debugging & Troubleshooting

"Get the logs from the last 100 lines of the api-server pod"
"Show me events related to the failing deployment"
"Execute a shell command in the debug container"
"Why is my pod not starting? Help me troubleshoot"

Scaling & Updates

"Scale the web-app deployment to 10 replicas"
"Roll out a new version of the frontend service"
"Pause the rollout of the database deployment"
"Show me the rollout history for the api service"

🔧 Configuration

Environment Variables

Variable	Description	Default
`KUBECONFIG`	Path to kubeconfig file	`~/.kube/config`
`K8S_CONTEXT`	Default Kubernetes context	Current context
`LOG_LEVEL`	Logging level (DEBUG, INFO, WARN, ERROR)	`INFO`
`LOG_FILE`	Log file path	`stdout`

Command Line Options

./mcp-k8swizard --help

Options:
  -log-level string
        Set log level (DEBUG, INFO, WARN, ERROR)
  -verbose
        Enable verbose logging (equivalent to DEBUG level)
  -version
        Show version information
  -help
        Show help information

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

Development Commands

# Build the project
make build

# Install dependencies
make deps

# Format code
make fmt

# Run linter
make lint

# Run go vet
make vet

# Clean build artifacts
make clean

Code Style

Follow Go standard formatting (gofmt)
Use meaningful variable and function names
Add comments for public functions

📄 License

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

🙏 Acknowledgments

Model Context Protocol for the MCP specification
Kubernetes for the amazing container orchestration platform
Go for the excellent programming language
The open-source community for inspiration and support

📚 Documentation

Manuals

Installation Manual - Complete setup guide for Cursor AI integration
Configuration Guide - Advanced configuration options
Troubleshooting Guide - Common issues and solutions
API Reference - Complete tool documentation

Quick Links

Getting Started: See Installation Manual for detailed setup
Configuration: Advanced options in Configuration Guide
Troubleshooting: Common issues in Troubleshooting Guide

📞 Support

Documentation: Wiki
Issues: GitHub Issues
Discussions: GitHub Discussions

Made with ❤️ for the Kubernetes community