Skip to main content
Glama
mcp-kubernetes-server

mcp-kubernetes-server

by ductnn

Kubernetes MCP Server

Python Version License

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

Related MCP server: mcp-kubernetes-server

📦 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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables interaction with Kubernetes/Minikube clusters through natural language, allowing AI agents like Codename Goose to manage Kubernetes resources via the Model Context Protocol.
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables AI assistants to interact with Kubernetes clusters by translating natural language into kubectl and Helm operations. It allows users to query, manage, and diagnose Kubernetes resources and cluster states through a seamless integration.
      19
      Apache 2.0
    • A
      license
      B
      quality
      B
      maintenance
      A production-grade MCP server providing a secure, natural-language interface to Kubernetes for developers and AI agents, with multi-cluster routing, OIDC authentication, RBAC, and audit logging.
      75
      71 npm
      1
      MIT