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:
kubectlcommand 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
kubectlconfigured locally- UV installed```bash
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:```python
# 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:```python
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:```json
{
"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:```bash
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.
