K8s Mcp Server

Kubernetes 和 Helm MCP 服务

一个简单可靠的 MCP（Model Context Protocol）服务，专为 Kubernetes 和 Helm 环境管理设计，并支持与 n8n 集成。

功能特性

• 原生支持 n8n - 完美支持 n8n MCP 客户端节点
• SSE 连接 - 使用 Server-Sent Events 实现实时双向通信
• Kubernetes 集成 - 提供完整的 kubectl 工具访问能力
• Helm 支持 - 提供 Helm chart 和 release 管理功能
• 模块化架构 - 清晰分离入口点和服务实现

文件结构

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

架构说明

• src/index.js - 主程序入口，负责：

  • 命令行参数解析
  • 环境变量配置
  • 生命周期管理
  • 优雅关闭处理
  • 错误处理

• src/server.js - 服务实现，负责：

  • MCP 服务配置和工具注册
  • 创建 Express 应用（SSE 模式）
  • MCP 消息处理
  • SSE 连接管理

快速开始

本地开发

1. 安装依赖

npm install

2. 启动 SSE 模式（用于 n8n）

npm run start:http
# Or specify port
npm run start:http -- --port 3001

3. 检查服务状态

curl http://localhost:3001/health

Docker 部署

1. 构建镜像

docker build -t k8s-mcp-server .

2. 启动容器（需要挂载 kubeconfig）

⚠️ 重要： 启动容器时，需要将本地 .kube/config 挂载到容器的 /home/nodejs/.kube/config 路径，以便 MCP 服务能够访问 Kubernetes 集群。

# Use local kubeconfig
docker run -p 3001:3000 \
  -v ~/.kube/config:/home/nodejs/.kube/config:ro \
  k8s-mcp-server

3. 自定义 kubeconfig 路径

# Use custom kubeconfig file
docker run -p 3001:3000 \
  -v /path/to/your/kubeconfig:/home/nodejs/.kube/config:ro \
  k8s-mcp-server

4. 使用 Service Account Token（在 Kubernetes 内部部署）

# 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. 验证连接

容器启动后，可以检查 Kubernetes 连接状态：

# 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. 重要说明

权限要求：

• 确保 kubeconfig 文件具有适当的 Kubernetes 集群访问权限
• 建议使用只读服务账号以提高安全性
• 容器以 nodejs 用户身份运行，请确保挂载的文件具有适当的读取权限

故障排除：

# 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 示例：

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

与 n8n 搭配使用

第 1 步：启动 MCP 服务

确保 MCP 服务以 SSE 模式运行：

cd k8s-mcp/k8s-mcp-server
npm run start:http -- --port 3001

服务启动后，你将看到：

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