K3s MCP Server

MCP运维云端

提供方 ry-ops

运维云端 stdio · 本地进程 无需鉴权 社区 / 第三方 Claude DesktopClaude
查看接入方式

一个基于Model Context Protocol (MCP)的K3s集群管理服务器,支持通过自然语言管理Kubernetes集群,是AI原生基础设施编排系统Cortex Platform的核心组件。

一句话选型结论

按资料字段整理

K3s MCP Server 属于运维云端类 MCP 服务器,stdio · 本地进程,无需鉴权,可直接接入 Claude Desktop、Claude,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类运维云端 传输方式stdio · 本地进程 鉴权无需鉴权 部署方式本地部署
GitHub 星标 2 仓库热度,无公开仓库时显示未标注
工具数 13 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

运维云端
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量13暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

Kubernetes管理Python本地部署AI基础设施服务器自动化集群编排自然语言处理

安装与配置

stdio · 本地进程 无需鉴权
客户端在本机拉起子进程,数据不出本机
uv run k3s-mcp-server

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Python,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 13 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
云资源查询

查实例、存储、账单等云上资源状态。

部署与发布

把部署、重启、回滚这类操作接进对话。

监控与告警

拉取监控指标,异常时让模型帮你判断。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 13 个工具,覆盖面较广,能满足多种调用。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude Desktop、Claude,换客户端不用重新研究配置。
  • 资料标注无需鉴权,装好就能连。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在运维云端场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
K3s MCP Server当前 13 stdio · 本地进程 本地部署 有 2026-05-17
lobehub 未标注 stdio · 本地进程 本地部署 有 2026-04-11
TrendRadar 未标注 stdio · 本地进程 本地部署 有 2026-04-13
Ui Tars Desktop 8a825770 未标注 stdio · 本地进程 本地部署 有 2026-05-17
ruflo 未标注 stdio · 本地进程 本地部署 有 2026-04-13
FastGPT 未标注 stdio · 本地进程 本地部署 有 2026-04-11

服务器档案

运维云端
字段来自项目仓库与公开索引,中文说明由本站标注
提供方ry-ops上游标注的维护方 ry-ops
分类运维云端本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式无需鉴权远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · Python本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

23.4 KB
来自项目仓库与上游目录的原文,未做删改

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: &quot;Block the client with MAC aa:bb:cc:dd:ee:ff&quot;
│
▼
┌─────────────────────────────────────────────────────────────┐
│ TIER 1: Keyword Pattern Match (&lt;10ms)                       │
│                                                             │
│ Pattern: &quot;(block|unblock).*client&quot; → MATCH                  │
│ Confidence: 95%                                             │
│ Action: Route directly to execution-unifi-api               │
└─────────────────────────────────────────────────────────────┘
│
│ (If no match, continue to Tier 2)
▼
┌─────────────────────────────────────────────────────────────┐
│ TIER 2: Qdrant Similarity Search (&lt;50ms)                    │
│                                                             │
│ Query embedding → Search past successful routes             │
│ If similar query succeeded before → Reuse routing           │
│ Learning: Skip expensive LLM classification                 │
└─────────────────────────────────────────────────────────────┘
│
│ (If similarity &lt; 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检测到指标&gt;阈值→ 扩展部署0→1
1. Pod启动→ 健康调查通过→ Pod就绪
1. 请求已处理→ 已发送响应
1. 5分钟空闲→ 冷却触发器→ 缩回到0

### 自适应智能(第四阶段)

查询复杂度评分(0-100)决定执行模式:

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

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

- 低置信度(\&lt;50%)→升级模式
- 以前的类似查询失败→ 升级
- 超时(&gt;30s代理,&gt;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=&quot;$HOME/.kube/config&quot;

# 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
{
&quot;mcpServers&quot;: {
&quot;k3s&quot;: {
&quot;command&quot;: &quot;uv&quot;,
&quot;args&quot;: [
&quot;--directory&quot;,
&quot;/absolute/path/to/k3s-mcp-server&quot;,
&quot;run&quot;,
&quot;k3s-mcp-server&quot;
],
&quot;env&quot;: {
&quot;KUBECONFIG&quot;: &quot;/path/to/.kube/config&quot;
}
}
}
}

可用工具

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原生基础架构编排

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
K3s MCP Server 怎么安装?

在客户端按下面的安装命令接入:uv run k3s-mcp-server。装完在客户端配置里引用同一个包或端点。

K3s MCP Server 怎么在 Claude Desktop、Claude 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

K3s MCP Server 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

K3s MCP Server 需要 API Key 吗?

资料标注为无需认证,装好就能连;如果实际调用时报鉴权错误,按官方文档补上凭据。

K3s MCP Server 支持哪些客户端?

资料标注支持 Claude Desktop、Claude;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

K3s MCP Server 能提供哪些能力?

资料显示约 13 个工具;能力标签包括 Kubernetes管理、Python、Claude。具体工具清单以官方文档为准。

K3s MCP Server 需要什么运行环境?

运行时为 Python;属于本地进程,需要在本机装好运行环境。

K3s MCP Server 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。