K3s MCP服务器
用于管理Kubernetes(K3)集群的模型上下文协议(MCP)服务器。该服务器使像Claude这样的人工智能助手能够通过自然语言管理K3集群,并作为 Cortex平台 -AI原生基础设施编排系统。
Cortex平台:K3上的AI原生基础设施
该项目是 Cortex平台,一个展示先进K3使用模式的生产系统:
- 7层无服务器结构 具有KEDA自动缩放功能(按需0→1个吊舱)
- 人工智能驱动的查询路由 具有多层分类
- 自我修复基础设施 通过基于MCP的自动化
- 矢量存储器(Qdrant) 从操作模式中学习
- 动态工人池 由AI代理管理
架构概述```
┌─────────────────────────────────────────────────────────────────────────────┐
│ CORTEX PLATFORM │
│ AI-Native K3s Infrastructure │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ K3s CLUSTER (7 nodes) │ │
│ │ Talos Linux + etcd HA │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────┐ │ │
│ │ │ UNIFI LAYER FABRIC │ │ │
│ │ │ Serverless AI Network Operations │ │ │
│ │ │ │ │ │
│ │ │ USER QUERY │ │ │
│ │ │ │ │ │ │
│ │ │ ▼ │ │ │
│ │ │ ┌───────────────────┐ ┌─────────────────┐ │ │ │
│ │ │ │ CORTEX ACTIVATOR │───▶│ CORTEX QDRANT │ │ │ │
│ │ │ │ (Always On) │ │ (Always On) │ │ │ │
│ │ │ │ Query Router │ │ Vector Memory │ │ │ │
│ │ │ │ 128MB, 2 pods │ │ 512MB, 5Gi PVC │ │ │ │
│ │ │ └─────────┬─────────┘ └─────────────────┘ │ │ │
│ │ │ │ │ │ │
│ │ │ │ 4-Tier Routing Cascade │ │ │
│ │ │ │ 2. Similarity Search (<50ms) │ │ │
│ │ │ │ 3. Lightweight Classifier (~5s cold) │ │ │
│ │ │ │ 4. Full SLM Reasoning (~12s cold) │ │ │
│ │ │ ▼ │ │ │
│ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │
│ │ │ │ REASONING LAYERS (Scale 0→1) │ │ │ │
│ │ │ │ │ │ │ │
│ │ │ │ ┌──────────────────┐ ┌──────────────────────┐ │ │ │ │
│ │ │ │ │ reasoning- │ │ reasoning-slm │ │ │ │ │
│ │ │ │ │ classifier │ │ │ │ │ │ │
│ │ │ │ │ Qwen2 0.5B │ │ Phi-3 3.8B │ │ │ │ │
│ │ │ │ │ ~5s cold start │ │ ~12s cold start │ │ │ │ │
│ │ │ │ │ 400MB warm │ │ 2.5GB warm │ │ │ │ │
│ │ │ │ └──────────────────┘ └──────────────────────┘ │ │ │ │
│ │ │ └─────────────────────────────────────────────────────┘ │ │ │
│ │ │ │ │ │ │
│ │ │ ▼ │ │ │
│ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │
│ │ │ │ EXECUTION LAYERS (Scale 0→1) │ │ │ │
│ │ │ │ │ │ │ │
│ │ │ │ ┌──────────────────┐ ┌──────────────────────┐ │ │ │ │
│ │ │ │ │ execution- │ │ execution- │ │ │ │ │
│ │ │ │ │ execution- │ │ execution- │ │ │ │ │
│ │ │ │ │ execution- │ │ execution- │ │ │ │ │
│ │ │ │ │ unifi-api │ │ unifi-ssh │ │ │ │ │
│ │ │ │ │ unifi-api │ │ unifi-ssh │ │ │ │ │
│ │ │ │ │ Primary │ │ Failover │ │ │ │ │
│ │ │ │ │ ~3s cold start │ │ ~3s cold start │ │ │ │ │
│ │ │ │ └──────────────────┘ └──────────────────────┘ │ │ │ │
│ │ │ └─────────────────────────────────────────────────────┘ │ │ │
│ │ │ │ │ │ │
│ │ │ ▼ │ │ │
│ │ │ ┌───────────────────┐ │ │ │
│ │ │ │ CORTEX TELEMETRY │ │ │ │
│ │ │ │ Metrics + Learning│ │ │ │
│ │ │ │ Scale 0→1 │ │ │ │
│ │ │ └───────────────────┘ │ │ │
│ │ └─────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────┐ │ │
│ │ │ MCP SERVERS │ │ │
│ │ │ │ │ │
│ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │
│ │ │ │ k3s-mcp │ │ talos-mcp │ │ proxmox-mcp │ │ │ │
│ │ │ │ (this repo) │ │ │ │ │ │ │ │
│ │ │ │ Cluster ops │ │ Node mgmt │ │ VM lifecycle │ │ │ │
│ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │
│ │ └─────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────┐ │ │
│ │ │ DYNAMIC WORKER POOLS │ │ │
│ │ │ (Managed by AI Resource Manager) │ │ │
│ │ │ │ │ │
│ │ │ Permanent: 3-10 nodes (always running) │ │ │
│ │ │ Burst: 0-20 nodes (TTL-based cleanup) │ │ │
│ │ │ Spot: 0-15 nodes (70% cost savings) │ │ │
│ │ │ GPU: 0-5 nodes (special hardware taints) │ │ │
│ │ └─────────────────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ Memory Profile: │
│ • Idle: 640MB (Activator + Qdrant only) │
│ • Simple query: 1GB (+ execution layer) │
│ • Complex: 4GB (+ SLM reasoning) │
│ • Savings: 85%+ vs always-on architecture │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
### 7层
|层|组件|目的|内存|冷启动|规模|
|-------|-----------|---------|--------|------------|-------|
| 1 | **皮质激活剂** |查询路由和编排|128MB|始终打开|2个副本|
| 2 | **皮质qdrant** |矢量内存和RAG | 512MB |始终打开| 1个副本|
| 3 | **推理分类器** |快速意图分类|400MB|~5s|0→1 |
| 4 | **推理slm** |完整推理(Phi-3)|2.5GB|~12s |0→1 |
| 5 | **执行unifiapi** |主要API操作|200MB|~3s|0→2 |
| 6 | **执行unifi-ssh** |故障切换和诊断|100MB|~3s|0→1 |
| 7 | **皮层遥测** |指标和学习管道|128MB|~2s|0→1 |
### Cortex激活器:智能查询路由器
Cortex Activator是系统的大脑——一个轻量级的服务,通过4层级联路由查询:```
Query: "Block the client with MAC aa:bb:cc:dd:ee:ff"
│
▼
┌─────────────────────────────────────────────────────────────┐
│ TIER 1: Keyword Pattern Match (<10ms) │
│ │
│ Pattern: "(block|unblock).*client" → MATCH │
│ Confidence: 95% │
│ Action: Route directly to execution-unifi-api │
└─────────────────────────────────────────────────────────────┘
│
│ (If no match, continue to Tier 2)
▼
┌─────────────────────────────────────────────────────────────┐
│ TIER 2: Qdrant Similarity Search (<50ms) │
│ │
│ Query embedding → Search past successful routes │
│ If similar query succeeded before → Reuse routing │
│ Learning: Skip expensive LLM classification │
└─────────────────────────────────────────────────────────────┘
│
│ (If similarity < 92%, continue to Tier 3)
▼
┌─────────────────────────────────────────────────────────────┐
│ TIER 3: Lightweight Classifier (~5s cold start) │
│ │
│ Model: Qwen2-0.5B (quantized) │
│ Use: Ambiguous queries needing quick classification │
│ KEDA: Scales from 0→1 on demand │
└─────────────────────────────────────────────────────────────┘
│
│ (If complex investigation needed, continue to Tier 4)
▼
┌─────────────────────────────────────────────────────────────┐
│ TIER 4: Full SLM Reasoning (~12s cold start) │
│ │
│ Model: Phi-3-mini-4k-instruct (3.8B, quantized) │
│ Use: Multi-step reasoning, complex troubleshooting │
│ KEDA: Scales from 0→1 on demand │
└─────────────────────────────────────────────────────────────┘
KEDA无服务器扩展
根据Prometheus指标,图层从0扩展到1:```yaml
reasoning-slm KEDA configuration
keda:
minReplicaCount: 0 # Scale to zero when idle
maxReplicaCount: 1
cooldownPeriod: 300 # Scale down after 5 min idle
trigger:
type: prometheus
query: sum(cortex_activator_pending_requests{layer="reasoning-slm"})
threshold: "1" # Wake if ANY pending request
**激活流程:**
1. 查询到达→ 激活器增量 `pending_requests` 测量
1. KEDA检测到指标>阈值→ 扩展部署0→1
1. Pod启动→ 健康调查通过→ Pod就绪
1. 请求已处理→ 已发送响应
1. 5分钟空闲→ 冷却触发器→ 缩回到0
### 自适应智能(第四阶段)
查询复杂度评分(0-100)决定执行模式:
|复杂性|得分|模式|资源|
|------------|-------|------|-----------|
|简单|0-25|直接执行|仅限激活器|
|中等|26-50|基本分类|+分类器|
|复杂|51-75|充分推理|+SLM|
|专家|76-100|升级|人工审查|
**自动升级触发器:**
- 低置信度(\<50%)→升级模式
- 以前的类似查询失败→ 升级
- 超时(>30s代理,>60s混合)→ 升级
______________________________________________________________________
## K3s MCP服务器功能
此MCP服务器为AI驱动的集群管理提供了基础:
### Pod管理
- 使用标签选择器跨命名空间列出Pod
- 获取带有尾部和容器选择的pod日志
- 在Pod中执行命令
- 重启Pod(删除并重新创建)
### 部署管理
- 列出并描述部署
- 向上或向下扩展部署
- 获取部署状态和副本计数
### 服务管理
- 列出服务和端点
- 查看服务端口和选择器
- 检查服务类型(ClusterIP、NodePort、LoadBalancer)
### 节点管理
- 列出所有群集节点
- 获取节点状态和资源
- 查看节点容量和可分配资源
- 检查节点状态(就绪、内存压力等)
### 资源管理
- 应用YAML清单
- 删除资源(Pod、部署、服务)
- 列出命名空间
- 获取集群信息
## 快速开始```bash
# 1. Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh
# 2. Clone this repository
git clone https://github.com/ry-ops/k3s-mcp-server.git
cd k3s-mcp-server
# 3. Run setup script
chmod +x setup.sh
./setup.sh
# 4. Set environment variables
export KUBECONFIG="$HOME/.kube/config"
# 5. Test the server
uv run k3s-mcp-server
# 6. Configure Claude Desktop and restart
看 QUICKSTART.md 详细说明。
安装
先决条件
- Python 3.10或更高版本
uv包管理器- 具有kubeconfig访问权限的K3s集群
- Kubeconfig文件
设置```bash
Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
Clone this repository
git clone https://github.com/ry-ops/k3s-mcp-server.git
cd k3s-mcp-server
Run setup script (creates structure and installs dependencies)
./setup.sh
Or manually:
uv sync
## 配置
### 环境变量
|变量|描述|默认值|
|----------|-------------|---------|
| `KUBECONFIG` |kubeconfig文件的路径| `~/.kube/config` |
| `K3S_DEFAULT_NAMESPACE` |默认命名空间| `default` |
| `K3S_DEBUG` |启用调试日志记录| `false` |
### Claude桌面配置
**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**视窗**: `%APPDATA%/Claude/claude_desktop_config.json````json
{
"mcpServers": {
"k3s": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/k3s-mcp-server",
"run",
"k3s-mcp-server"
],
"env": {
"KUBECONFIG": "/path/to/.kube/config"
}
}
}
}
可用工具
Pod工具
| 工具 | 说明 | 参数 |
|---|---|---|
get_pods |
在命名空间或集群范围内列出Pod | namespace, labels |
get_logs |
获取pod日志 | pod_name, namespace, container, tail_lines |
restart_pod |
通过删除来重新启动pod | name, namespace |
execute_command |
在pod中执行命令 | pod_name, namespace, command, container |
部署工具
| 工具 | 说明 | 参数 |
|---|---|---|
get_deployments |
列出所有部署 | namespace |
get_deployment |
获取具体的部署详细信息 | name, namespace |
scale_deployment |
扩展部署副本 | name, namespace, replicas |
群集工具
| 工具 | 说明 | 参数 |
|---|---|---|
get_nodes |
列出所有具有资源的节点 | - |
get_services |
列出所有服务 | namespace |
get_cluster_info |
获取群集版本和摘要 | - |
get_namespaces |
列出所有命名空间 | - |
apply_manifest |
应用YAML清单 | manifest_yaml, namespace |
delete_resource |
删除资源 | kind, name, namespace |
示例用法
配置后,让Claude与您的K3集群交互:```
"List all pods in the cortex-system namespace"
"What's the status of the cortex-activator deployment?"
"Scale reasoning-slm to 1 replica"
"Show me logs from the cortex-qdrant pod"
"Which nodes are in my cluster and what's their capacity?"
"Apply this deployment manifest: [YAML content]"
## 项目结构```
k3s-mcp-server/
├── src/
│ └── k3s_mcp_server/
│ ├── __init__.py # Package initialization
│ └── server.py # Main server implementation
├── docs/
│ ├── ARCHITECTURE.md # Detailed architecture docs
│ └── CORTEX_INTEGRATION.md # Cortex Platform integration
├── pyproject.toml # Project configuration
├── uv.lock # Locked dependencies
├── setup.sh # Automated setup script
├── README.md # This file
└── QUICKSTART.md # Quick setup guide
使用的K3s功能
该项目演示了K3功能的生产使用:
| 功能 | 用法 |
|---|---|
| 命名空间 | 多租户隔离(皮质系统、皮质mcp、皮质unifi) |
| 部署 | 所有具有滚动更新的工作负载 |
| 科达 | 无服务器0→1 推理/执行层的扩展 |
| 舵 | 所有组件的包管理 |
| 基于角色的访问控制 | 细粒度服务帐户权限 |
| 室性早搏 | Qdrant矢量数据库的持久存储 |
| ConfigMaps/Secrets | 配置管理 |
| 健康探测器 | 活力、准备、启动探测 |
| 资源限制 | CPU/内存请求和限制 |
| Pod抗亲和力 | 节点间的HA分布 |
| ArgoCD | GitOps持续部署 |
安全考虑
- Kubeconfig安全:确保kubeconfig文件的安全(chmod 600)
- 基于角色的访问控制:确保kubeconfig用户有适当的权限
- 网络接入:与K3s API服务器的安全网络连接
- 审计:K8s API服务器记录所有操作以进行审核
故障排除
连接错误
- 验证
KUBECONFIG路径正确,文件存在 - 检查K3s服务器的网络连接
- 测试:
kubectl --kubeconfig /path/to/config get nodes
身份验证错误
- 验证kubeconfig是否包含有效凭据
- 检查证书是否有效且未过期
Claude中未显示的工具
- 验证Claude配置中的绝对路径
- 检查配置文件是否为有效的JSON
- 完全重新启动克劳德桌面
调试模式```bash
export K3S_DEBUG=true
uv run k3s-mcp-server
```
路线图
- []ConfigMap和密钥管理
- []持续的体积和PVC操作
- []入口管理
- []Job和CronJob支持
- []StatefulSet操作
- []水平跑道自动标度器(HPA)配置
- []Helm chart部署支持
- []KEDA缩放对象管理
依赖项
- 主控程序 (>=1.0.0):模型上下文协议SDK
- Kubernetes (>=29.0.0):Kubernetes的官方Python客户端
- 格式 (>=6.0):用于清单处理的YAML解析器
贡献
欢迎投稿!需要改进的地方:
- 其他资源类型
- 更好的错误处理
- 性能优化
- 文档改进
- 测试覆盖率
许可证
麻省理工学院
相关项目
- 模型上下文协议
- K3s-轻量级Kubernetes
- KEDA-Kubernetes事件驱动的自动缩放
- Qdrant-矢量数据库
- uv-Python包管理器
Cortex平台的一部分 -K3上的AI原生基础架构编排
