kopp0510/k8s-mcp-server
If you are the rightful owner of k8s-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
A simple, reliable MCP Server designed for Kubernetes and Helm environment management, with n8n integration support.
kubectl-get
Resource query tool (supports label filtering)
kubectl-logs
Pod log viewing tool
kubectl-describe
Resource detailed description tool
kubectl-cluster-info
Cluster information query tool
kubectl-get-yaml
Resource YAML format output tool
kubectl-top-nodes
Node resource usage monitoring
kubectl-top-pods
Pod resource usage monitoring
kubectl-top-containers
Container resource usage monitoring
kubectl-scale-deployment
Deployment scaling tool
kubectl-restart-deployment
Deployment restart tool
kubectl-edit-hpa
HPA editing tool
helm-list
Helm release list tool
helm-status
Helm release status tool
helm-repo-list
Helm repository list tool
helm-get-values
Helm release configuration values tool
helm-history
Helm release history tool
Kubernetes & Helm MCP Server
A simple, reliable MCP (Model Context Protocol) Server designed for Kubernetes and Helm environment management, with n8n integration support.
Features
- Native n8n Support - Perfect support for n8n MCP Client nodes
- SSE Connection - Uses Server-Sent Events for real-time bidirectional communication
- Kubernetes Integration - Provides complete kubectl tool access
- Helm Support - Provides Helm chart and release management functionality
- Modular Architecture - Clear separation between entry point and server implementation
File Structure
k8s-mcp-server/
āāā src/ # Source code directory
ā āāā index.js # Main program entry, handles lifecycle and parameter parsing
ā āāā server.js # MCP + Express integration, server implementation
ā āāā tools/ # Tool modules
ā ā āāā base-tool.js # Base tool class
ā ā āāā kubectl-get.js # Resource query tool (supports label filtering)
ā ā āāā kubectl-logs.js # Pod log viewing tool
ā ā āāā kubectl-describe.js # Resource detailed description tool
ā ā āāā kubectl-cluster-info.js # Cluster information query tool
ā ā āāā kubectl-get-yaml.js # Resource YAML format output tool
ā ā āāā kubectl-top-nodes.js # Node resource usage monitoring
ā ā āāā kubectl-top-pods.js # Pod resource usage monitoring
ā ā āāā kubectl-top-containers.js # Container resource usage monitoring
ā ā āāā kubectl-scale-deployment.js # Deployment scaling tool
ā ā āāā kubectl-restart-deployment.js # Deployment restart tool
ā ā āāā kubectl-edit-hpa.js # HPA editing tool
ā ā āāā helm-list.js # Helm release list tool
ā ā āāā helm-status.js # Helm release status tool
ā ā āāā helm-repo-list.js # Helm repository list tool
ā ā āāā helm-get-values.js # Helm release configuration values tool
ā ā āāā helm-history.js # Helm release history tool
ā āāā utils/ # Utility functions
ā āāā logger.js # Logging system
ā āāā validator.js # Input validation (including label validation)
ā āāā kubectl.js # kubectl execution tool
ā āāā helm.js # helm execution tool
āāā package.json # Project configuration and dependencies
āāā package-lock.json # Dependency lock file
āāā Dockerfile # Docker container build file
āāā build.sh # Docker build script
āāā .gitignore # Git ignore file configuration
āāā .cursorignore # Cursor editor ignore file configuration
āāā README.md # Project documentation
Architecture Description
-
src/index.js
- Main program entry, responsible for:- Command line parameter parsing
- Environment variable configuration
- Lifecycle management
- Graceful shutdown handling
- Error handling
-
src/server.js
- Server implementation, responsible for:- MCP Server configuration and tool registration
- Express application creation (SSE mode)
- MCP message processing
- SSE connection management
Quick Start
Local Development
- Install Dependencies
npm install
- Start SSE Mode (for n8n)
npm run start:http
# Or specify port
npm run start:http -- --port 3001
- Check Service Status
curl http://localhost:3001/health
Docker Deployment
1. Build Image
docker build -t k8s-mcp-server .
2. Start Container (requires kubeconfig mounting)
ā ļø Important: When starting the container, you need to mount the local .kube/config
to the container's /home/nodejs/.kube/config
path so that the MCP Server can access the Kubernetes cluster.
# Use local kubeconfig
docker run -p 3001:3000 \
-v ~/.kube/config:/home/nodejs/.kube/config:ro \
k8s-mcp-server
3. Custom kubeconfig Path
# Use custom kubeconfig file
docker run -p 3001:3000 \
-v /path/to/your/kubeconfig:/home/nodejs/.kube/config:ro \
k8s-mcp-server
4. Use Service Account Token (Kubernetes Internal Deployment)
# When deploying inside a Kubernetes cluster, you can use service account
docker run -p 3001:3000 \
-v /var/run/secrets/kubernetes.io/serviceaccount:/var/run/secrets/kubernetes.io/serviceaccount:ro \
-e KUBERNETES_SERVICE_HOST \
-e KUBERNETES_SERVICE_PORT \
k8s-mcp-server
5. Verify Connection
After the container starts, you can check the Kubernetes connection status:
# Check service status
curl http://localhost:3001/health
# Test Kubernetes connection
curl -X POST http://localhost:3001/messages \
-H "Content-Type: application/json" \
-d '{
"method": "tools/call",
"params": {
"name": "kubectl_get",
"arguments": {"resource": "nodes"}
}
}'
6. Important Notes
Permission Requirements:
- Ensure the kubeconfig file has appropriate Kubernetes cluster access permissions
- It's recommended to use read-only service accounts for improved security
- The container runs as the
nodejs
user, ensure mounted files have appropriate read permissions
Troubleshooting:
# Check kubeconfig file permissions
ls -la ~/.kube/config
# Verify kubeconfig validity
kubectl --kubeconfig ~/.kube/config get nodes
# Check kubeconfig inside container
docker exec -it <container-id> cat /home/nodejs/.kube/config
Docker Compose Example:
version: '3.8'
services:
k8s-mcp-server:
build: .
ports:
- "3001:3000"
volumes:
- ~/.kube/config:/home/nodejs/.kube/config:ro
environment:
- NODE_ENV=production
restart: unless-stopped
Using with n8n
Step 1: Start MCP Server
Ensure the MCP Server is running in SSE mode:
cd k8s-mcp/k8s-mcp-server
npm run start:http -- --port 3001
After the server starts, you will see:
MCP Server started at http://localhost:3001
SSE endpoint: http://localhost:3001/sse (n8n connects here)
Message endpoint: http://localhost:3001/messages
Health check: http://localhost:3001/health
SSE mode - designed for n8n