K3s MCP Server

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 (阈值→ 扩展部署0→1
1. Pod启动→ 健康调查通过→ Pod就绪
1. 请求已处理→ 已发送响应
1. 5分钟空闲→ 冷却触发器→ 缩回到0

### 自适应智能（第四阶段）

查询复杂度评分（0-100）决定执行模式：

|复杂性|得分|模式|资源|
|------------|-------|------|-----------|
|简单|0-25|直接执行|仅限激活器|
|中等|26-50|基本分类|+分类器|
|复杂|51-75|充分推理|+SLM|
|专家|76-100|升级|人工审查|

**自动升级触发器：**

- 低置信度（\30s代理，>60s混合）→ 升级

______________________________________________________________________

## K3s MCP服务器功能

此MCP服务器为AI驱动的集群管理提供了基础：

### Pod管理

- 使用标签选择器跨命名空间列出Pod
- 获取带有尾部和容器选择的pod日志
- 在Pod中执行命令
- 重启Pod（删除并重新创建）

### 部署管理

- 列出并描述部署
- 向上或向下扩展部署
- 获取部署状态和副本计数

### 服务管理

- 列出服务和端点
- 查看服务端口和选择器
- 检查服务类型（ClusterIP、NodePort、LoadBalancer）

### 节点管理

- 列出所有群集节点
- 获取节点状态和资源
- 查看节点容量和可分配资源
- 检查节点状态（就绪、内存压力等）

### 资源管理

- 应用YAML清单
- 删除资源（Pod、部署、服务）
- 列出命名空间
- 获取集群信息

## 快速开始

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](QUICKSTART.md) 详细说明。

## 安装

### 先决条件

- Python 3.10或更高版本
- `uv` 包管理器
- 具有kubeconfig访问权限的K3s集群
- Kubeconfig文件

### 设置

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`

{ "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
- 完全重新启动克劳德桌面

### 调试模式

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解析器

## 贡献

欢迎投稿！需要改进的地方：

- 其他资源类型
- 更好的错误处理
- 性能优化
- 文档改进
- 测试覆盖率

## 许可证

麻省理工学院

## 相关项目

- [模型上下文协议](https://modelcontextprotocol.io/)
- [K3s-轻量级Kubernetes](https://k3s.io/)
- [KEDA-Kubernetes事件驱动的自动缩放](https://keda.sh/)
- [Qdrant-矢量数据库](https://qdrant.tech/)
- [uv-Python包管理器](https://github.com/astral-sh/uv)

______________________________________________________________________

**Cortex平台的一部分** -K3上的AI原生基础架构编排