k8s-mcp-server

kopp0510/k8s-mcp-server

3.3

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.

Tools
  1. kubectl-get

    Resource query tool (supports label filtering)

  2. kubectl-logs

    Pod log viewing tool

  3. kubectl-describe

    Resource detailed description tool

  4. kubectl-cluster-info

    Cluster information query tool

  5. kubectl-get-yaml

    Resource YAML format output tool

  6. kubectl-top-nodes

    Node resource usage monitoring

  7. kubectl-top-pods

    Pod resource usage monitoring

  8. kubectl-top-containers

    Container resource usage monitoring

  9. kubectl-scale-deployment

    Deployment scaling tool

  10. kubectl-restart-deployment

    Deployment restart tool

  11. kubectl-edit-hpa

    HPA editing tool

  12. helm-list

    Helm release list tool

  13. helm-status

    Helm release status tool

  14. helm-repo-list

    Helm repository list tool

  15. helm-get-values

    Helm release configuration values tool

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

  1. Install Dependencies
npm install
  1. Start SSE Mode (for n8n)
npm run start:http
# Or specify port
npm run start:http -- --port 3001
  1. 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