aadarshjain/kubectl-mcp-server

A Model Context Protocol (MCP) server for Kubernetes cluster management and information gathering using kubectl commands and the Kubernetes Python client.
Table of Contents
- Overview
- Project Structure
- Features
- Installation
- Prerequisites
- Setup
- Running the Server
- Basic Usage
- Available Tools
- Configuration
- Kubeconfig Setup
- Claude Desktop Configuration
- Security
- Example Usage
- Troubleshooting
Overview
This MCP server provides a seamless interface between LLMs (like Claude) and Kubernetes clusters. It enables natural language interactions with your Kubernetes resources without manually running kubectl commands or writing complex API calls. The server supports both read-only operations for safe information gathering and full kubectl command execution when needed.
Project Structure
Features
- **Cluster Management**: List and switch between different Kubernetes contexts
- **Read-only Operations**: Safe kubectl commands for information gathering (get, describe, explain)
- **Full kubectl Support**: Execute any kubectl command when needed
- **Kubernetes API Integration**: Direct access to Kubernetes APIs through Python client
- **Context Switching**: Seamlessly switch between different cluster contexts
- **Safety Controls**: Built-in protection against destructive operations in read-only mode
Installation
Prerequisites
For local development and testing, you'll need:
System Requirements
- **Python 3.8+** - The MCP server is built with Python
- **kubectl** - Kubernetes command-line tool installed and configured
- **Kubernetes cluster access** - Valid kubeconfig with cluster credentials
Optional (for Claude Desktop integration)
- **Claude Desktop** application installed
- **Node.js and npm** (if using npx for mcp-remote)
Setup
1. Clone and navigate to the project:
2. Install dependencies:
3. Configure environment variables:
4. Ensure kubectl is installed and configured:
Running the Server
Basic Usage
Available Tools
1. list_clusters()
Lists all available Kubernetes clusters from your kubeconfig file.
**Returns:**
- List of available clusters with names and cluster information
- Currently active context
**Example:**
2. get_current_context()
Gets the current Kubernetes context being used by both the MCP server and the system.
**Returns:**
- Current context stored in MCP server
- System's current kubectl context
**Example:**
3. switch_context(context: str)
Switches to a different Kubernetes context.
**Parameters:**
- context (string): Name of the context to switch to
**Returns:**
- Success message or error details
**Example:**
4. run_kubectl_command_ro(command: str)
Executes read-only kubectl commands safely.
**Parameters:**
- command (string): kubectl command starting with "kubectl"
**Allowed Operations:**
- get - Retrieve resources
- describe - Show detailed resource information
- explain - Show resource documentation
- config view - View kubeconfig
- config get-contexts - List available contexts
- version - Show kubectl/cluster version
- api-resources - List available API resources
- cluster-info - Show cluster information
**Returns:**
- Command output or error message
**Example:**
5. run_kubectl_command(command: str)