Kubernetes MCP Server

A lightweight MCP server that provides natural language processing and API access to Kubernetes clusters, combining both kubectl commands and Kubernetes Python client.

https://github.com/user-attachments/assets/48e061cd-3e85-40ff-ab04-a1a2b9bbd152

✨ Features

• Natural Language Interface: Convert plain English queries to kubectl commands
  • List pods and deployments across all namespaces
  • Fallback to general resource listing for unsupported queries
• Full CRUD Operations:
  • 🆕 Create/Delete namespaces, pods, and deployments via API endpoints
  • 🔍 Inspect cluster resources
  • ✏️ Modify labels, annotations, and deployment configurations
  • 🗑️ Graceful deletion
  • 📊 Scale deployments
• Dual Execution Mode:
  • kubectl command integration
  • Kubernetes Python client (official SDK)
• Advanced Capabilities:
  • Namespace validation (DNS-1123 compliant)
  • Label filtering
  • Grace period control
  • Automatic command fallback
  • Resource management (CPU, memory)
  • Environment variable configuration

📦 Installation

Prerequisites

• Python 3.11+
• Kubernetes cluster access
• kubectl configured locally
• UV installed

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

# Create virtual environment
uv venv .venv

# Activate (Unix)
source .venv/bin/activate

# Install dependencies
uv pip install -r requirements.txt

🚀 Usage

Natural Language Processing

The server supports basic natural language queries for listing resources:

# List all pods
result = nl_processor.process("Show me all pods")

# List all deployments
result = nl_processor.process("Show me all deployments")

# Query with namespace
result = nl_processor.process("Show me all resources", "kube-system")

For more complex operations, use the dedicated API endpoints:

# Create a pod
pod_service.create_pod(
    name="my-pod",
    namespace="default",
    image="nginx:latest",
    labels={"app": "my-app"}
)

# Create a deployment
deployment_service.create_deployment(
    name="my-deployment",
    namespace="default",
    image="nginx:latest",
    replicas=3
)

# Delete a namespace
namespace_service.delete("my-namespace", force=True)

API Endpoints

The server provides RESTful endpoints for all operations:

• /api/pods - Pod operations
• /api/deployments - Deployment operations
• /api/namespaces - Namespace operations
• /api/cluster - Cluster operations
• /api/nlp - Natural language processing

🤖 Usage with AI Assistants

Claude Desktop

• Open your Claude Desktop and choose Settings -> choose mode Developer -> Edit config and open file claude_desktop_config.json and edit:

{
    "mcpServers": {
        "kubernetes": {
            "command": "/path-to-your-uv/uv",
            "args": [
                "--directory",
                "/path-you-project/", // Example for me /Users/ductn/mcp-kubernetes-server
                "run",
                "main.py"
            ]
        }
    }
}

• Then, restart your Claude Desktop and play :)

🧪 Testing

Run the test suite:

# Run all tests
pytest

# Run specific test file
pytest tests/unit/test_pod_service.py

# Run with coverage
pytest --cov=.

📝 License

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