Kubernetes MCP Server - Project Details

Project Overview

The Kubernetes MCP Server is a Model Content Protocol (MCP) server specifically designed for Kubernetes cluster management. It allows AI agents (such as Claude) to connect to and manage Kubernetes clusters through natural language commands, greatly simplifying the complexity of container orchestration and cluster operations.

Project Address: https://github.com/Flux159/mcp-server-kubernetes

Core Features

🎯 Cluster Connection and Management

• Automatically connects to the cluster configured in the current kubectl context.
• Supports various Kubernetes environments (minikube, Rancher Desktop, GKE, etc.).
• Fully compatible with existing kubeconfig configurations.

📦 Pod and Deployment Management

• Pod Operations: Create, describe, and delete Pods.
• Deployment Management: List all deployments, update replica counts.
• Custom Configuration: Supports creating custom Pod and deployment configurations.
• Log Viewing: Retrieve Pod logs for debugging (supports Pod, deployment, Job, and label selectors).

🌐 Service and Network Management

• Service Operations: Create, describe, delete, and update Services.
• Port Forwarding: Supports port forwarding for Pods or Services.
• Network Configuration: Full Kubernetes network management support.

🗂️ Resource and Configuration Management

• Namespaces: List all namespaces, create new namespaces.
• ConfigMaps: Create, get, update, and delete ConfigMaps.
• Node Management: List and describe cluster nodes.
• Scheduled Tasks: Create, list, and describe CronJobs.

⚙️ Helm Integration Support

• Chart Installation: Install Helm charts with custom values.
• Version Management: Supports version specification and custom repositories.
• Release Management: Uninstall and upgrade existing releases.
• Namespace Support: Full namespace isolation.

🔧 Advanced Features

• kubectl Support: kubectl explain and kubectl api-resources commands.
• Event Monitoring: Retrieve cluster event information.
• Non-Destructive Mode: Safe mode allowing only read and create/update operations.
• Real-time Monitoring: Supports real-time viewing of cluster status.

System Architecture

Architecture Diagram

Client (Claude/AI Agent)
    ↓
StdioTransport (Communication Transport Layer)
    ↓
MCP Server (Protocol Processing)
    ↓
Request Handler (Request Routing)
    ↓
KubernetesManager (K8s Manager)
    ↓
Kubernetes API (Cluster API)

Request Flow

1. Client Request: The AI agent sends a request via STDIO.
2. Transport Layer: StdioTransport forwards the request to the MCP server.
3. Routing Processing: The server routes the request to the appropriate handler.
4. Tool Execution: KubernetesManager executes specific K8s operations.
5. API Call: Interacts with the Kubernetes API.
6. Response Return: The processing result is returned layer by layer to the client.

Installation and Configuration

Environment Requirements

• kubectl: Installed and configured in PATH.
• kubeconfig: Valid kubeconfig file and context configuration.
• Kubernetes Cluster: Accessible cluster (minikube, GKE, EKS, etc.).
• Helm v3: Optional, if Helm features are to be used.
• Node.js: Runtime environment.

Quick Installation

Install via NPM (Recommended)

# Install globally
npm install -g mcp-server-kubernetes

# Or run directly using npx
npx mcp-server-kubernetes

Claude Desktop Integration

Edit the claude_desktop_config.json file:

{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": ["mcp-server-kubernetes"]
    }
  }
}

Connection Verification

After installation, you can:

1. Ask Claude to list your Pods.
2. Create a test deployment.
3. If there are errors, first run kubectl get pods in the terminal to verify the connection.

Development Environment Setup

Local Development

# Clone the repository
git clone https://github.com/Flux159/mcp-server-kubernetes.git
cd mcp-server-kubernetes

# Install dependencies (requires bun)
bun install

# Start in development mode (listen for file changes)
bun run dev

# Run unit tests
bun run test

# Build the project
bun run build

Use Cases and Examples

🚀 Daily Operations Scenarios

• "List the status of all Pods" - Quickly check cluster health.
• "Create an nginx deployment with 3 replicas" - Quickly deploy an application.
• "View the logs of the failing Pods in the default namespace" - Troubleshoot issues.
• "Forward the application port to localhost:8080" - Local debugging.

📊 Monitoring and Debugging

• "Show all events in the cluster" - Monitor cluster activity.
• "Describe the details of node-1" - Resource analysis.
• "View the recent CronJob executions" - Scheduled task monitoring.

🛠️ Application Deployment

• "Install the Redis chart using Helm" - Quickly deploy middleware.
• "Update the replica count of the web-app deployment to 5" - Scaling operation.
• "Create a ConfigMap for the production environment" - Configuration management.

Advanced Configuration

Non-Destructive Mode

Set the environment variable to enable safe mode:

export ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS=true

In this mode, only read and create/update operations are allowed, and delete operations are prohibited.

SSE Transport Protocol

Supports Server-Sent Events transport protocol. See the project's ADVANCED_README.md for detailed configuration.

Cluster Authentication

Supports various Kubernetes authentication methods:

• Certificate Authentication
• Token Authentication
• OIDC Authentication
• Cloud Provider IAM Integration

Technology Stack and Dependencies

Core Technologies

• Runtime: Node.js + Bun
• Protocol: Model Content Protocol (MCP)
• Kubernetes Client: Official Kubernetes JavaScript Client
• Transport Layer: STDIO Transport
• Package Management: Helm v3

Main Dependencies

• @kubernetes/client-node: Kubernetes official JS client
• @modelcontextprotocol/sdk: MCP protocol SDK
• commander: Command-line argument parsing
• yaml: YAML file processing

Related Projects and Ecosystem

MCP Ecosystem

• mcp-chat: CLI chat client for MCP servers
• MCP Inspector: MCP protocol debugging tool
• Claude Desktop: AI assistant desktop application that supports MCP

Kubernetes Toolchain

• kubectl: Official command-line tool
• Helm: Package manager
• minikube: Local development environment
• Rancher Desktop: Desktop Kubernetes environment

Application Prospects and Value

🎯 Improved Operational Efficiency

Operating Kubernetes clusters through natural language reduces the learning curve and improves operational efficiency. Even beginners can quickly get started with complex cluster management tasks.

🤖 Intelligent Operations

Combined with the intelligent analysis capabilities of AI agents, it can achieve:

• Automatic fault diagnosis
• Intelligent resource recommendations
• Predictive maintenance
• Automated deployment optimization

🔗 Seamless Integration

Fully compatible with the existing Kubernetes ecosystem, without changing existing workflows, and can gradually introduce AI-assisted operations.

📈 Future Development Directions

• Support more Kubernetes resource types
• Integrate more cloud-native tools
• Enhance security and permission control
• Support multi-cluster management
• Graphical operation interface

Summary

The Kubernetes MCP Server project represents an innovative attempt to combine AI and cloud-native technologies. It simplifies the complexity of Kubernetes cluster management through a natural language interface, allowing operations personnel to manage containerized applications more intuitively and efficiently.

Whether you are a Kubernetes novice or an experienced operations expert, this tool can significantly improve your work efficiency. Through integration with AI assistants such as Claude, it opens up new possibilities for intelligent operations and is a powerful addition to the modern DevOps toolchain.

With the continued development of cloud-native technologies and the continuous advancement of AI technology, it is believed that such tools will play an increasingly important role in future IT operations.