K8sGPT MCP 服务器实战指南:用 Model Context Protocol 让 AI 助手直接运维 Kubernetes 集群
K8sGPT MCP 服务器实战指南:用 Model Context Protocol 让 AI 助手直接运维 Kubernetes 集群
K8sGPT 在自身 CLI 之外,还内置了一个基于 Model Context Protocol(MCP)的服务器:它把 Kubernetes 集群的巡检、资源查询、日志抓取、过滤器管理与 AI 解释等能力封装成标准化的 tools、resources 和 prompts,供 Claude、ChatGPT 等 MCP 兼容客户端直接调用。读完本文,你将掌握如何启动 K8sGPT 的 MCP 服务器(stdio 与 HTTP 两种模式)、如何用 curl 以 JSON-RPC 2.0 协议调用全部 12 个工具、3 个资源与 3 个排障提示词,并理解这些能力在源码中的真实调用链与参数边界。
什么是 MCP?K8sGPT 为什么需要它
Model Context Protocol(MCP)是一个开放的标准化协议,用于让 AI 助手安全地连接外部数据源与工具。K8sGPT 通过它把 Kubernetes 操作暴露为标准化接口,使 AI 助手能够:
- 分析集群健康状况与问题(
analyze) - 查询 Kubernetes 各类资源(
list-resources/get-resource) - 获取 Pod 日志与集群事件(
get-logs/list-events) - 获取排障引导(
troubleshoot-pod等 prompts) - 管理 analyzer 过滤器(
add-filters/remove-filters/list-filters)
从源码结构看,K8sGPT 的 MCP 能力集中在 pkg/server/mcp.go(服务器主体与注册逻辑)、pkg/server/mcp_handlers.go(12 个工具的具体 handler 实现)与 pkg/server/mcp_prompts.go(3 个排障提示词),它们基于 mark3labs/mcp-go 库构建,入口由 cmd/serve/serve.go 中的 --mcp 系列参数控制。
快速开始:两种方式启动 MCP 服务器
Stdio 模式(本地 AI 助手默认)
k8sgpt serve --mcp
HTTP 模式(网络访问 / webhook)
k8sgpt serve --mcp --mcp-http --mcp-port 8089
用 curl 验证服务器
curl -X POST http://localhost:8089/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list"
}'
完整 serve 模式命令参考
README 中给出了同时启用 REST 服务、metrics 与 MCP 的完整组合:
# 仅启用 MCP 服务器(默认端口 8089)
k8sgpt serve --mcp --mcp-http
# 自定义 MCP 端口
k8sgpt serve --mcp --mcp-http --mcp-port 8089
# 完整 serve 模式
k8sgpt serve --mcp --mcp-http --port 8080 --metrics-port 8081 --mcp-port 8089
服务器模式详解
Stdio 模式(默认)
供 Claude Desktop 等本地 AI 助手使用,通过标准输入/输出与子进程通信:
k8sgpt serve --mcp
在 MCP 客户端中配置(如 Claude Desktop 的 claude_desktop_config.json):
{
"mcpServers": {
"k8sgpt": {
"command": "k8sgpt",
"args": ["serve", "--mcp"]
}
}
}
从源码看,stdio 模式在 pkg/server/mcp.go 中通过 server.NewStdioServer(mcpServer) 创建,Start() 会阻塞式执行 server.ServeStdio。
HTTP 模式
用于网络访问与 webhook 场景。服务器以无状态(stateless)模式运行,无需会话管理,每次请求彼此独立:
k8sgpt serve --mcp --mcp-http --mcp-port 8089
源码中 HTTP 模式通过 server.NewStreamableHTTPServer 启动,并显式传入 server.WithStateLess(true) 开启无状态模式(pkg/server/mcp.go),随后以 goroutine 方式监听 ":" + port 端口,这也是为什么文档中强调“每个请求都是独立的”。
命令行参数一览(来自 cmd/serve/serve.go)
| 参数 | 默认值 | 说明 |
|---|---|---|
--mcp |
false |
启用 MCP(Mission Control Protocol)服务器 |
--mcp-http |
false |
启用 MCP 的 HTTP 传输模式 |
--mcp-port |
8089 |
MCP 服务器监听端口 |
--port / -p |
8080 |
常规 gRPC 服务端口 |
--metrics-port / -m |
8081 |
metrics 服务端口(可用环境变量 K8SGPT_METRICS_PORT 覆盖) |
--backend / -b |
openai |
AI 后端提供方 |
--http |
false |
启用 REST/HTTP(gRPC-gateway) |
--filter |
空 | 可重复指定,向运行中的服务器注入过滤器 |
另外,启动前需要先通过 k8sgpt auth 配置 AI 后端;serve 在启动时会从配置或环境变量(K8SGPT_BACKEND、K8SGPT_PASSWORD、K8SGPT_MODEL、K8SGPT_TEMPERATURE 等)中解析 AI Provider,未配置会提示 Please run k8sgpt auth 并退出。
可用工具:12 个 Kubernetes 操作工具
MCP 服务器暴露了 12 个工具,覆盖集群分析、资源管理、排障、过滤器与集成管理。以下是按功能域的完整清单(参数名以源码中注册的 JSON Schema 为准)。
集群分析
analyze — 分析 Kubernetes 资源中的问题
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
namespace |
否 | string | 要分析的命名空间(留空表示全部命名空间) |
backend |
否 | string | 使用的 AI 后端(如 openai、azure、localai),缺省回退为服务器配置的后端 |
explain |
否 | boolean | 是否为问题提供 AI 解释 |
filters |
否 | array | 用于收窄分析范围的过滤器(如 ['Pods', 'Deployments']) |
从源码实现看(pkg/server/mcp.go),handleAnalyze 会将请求参数绑定到 AnalyzeRequest 结构体(该结构体还支持 language、labelSelector、noCache、maxConcurrency、withDoc、anonymize 等额外字段),然后调用 pkg/analysis 的 NewAnalysis 创建分析实例并执行 RunAnalysis()。有几个值得注意的默认行为:
backend为空时,回退到服务器 AI Provider 的名称,否则默认openai;filters未指定时,使用 viper 中存储的active_filters;maxConcurrency会被validateMaxConcurrency校验:<=0时默认取 10,超过 100 时封顶为 100,以防止过度的内存分配(pkg/server/mcp.go);explain=true时走 AI 解释并输出纯文本(内部会stripANSI去除 ANSI 转义序列);否则输出 JSON 格式的分析结果。
cluster-info — 获取集群信息与版本(无需参数)。实现中通过 Kubernetes Discovery Client 的 ServerVersion() 返回类似 Kubernetes v1.32.0 的字符串(pkg/server/mcp.go)。
资源管理
list-resources — 列出指定类型的 Kubernetes 资源
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
resourceType |
是 | string | 资源类型:pods、deployments、services、nodes、jobs、cronjobs、statefulsets、daemonsets、replicasets、configmaps、secrets、ingresses、pvcs、pvs |
namespace |
否 | string | 查询的命名空间 |
labelSelector |
否 | string | 标签选择器过滤 |
get-resource — 获取某个具体资源的详细信息
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
resourceType |
是 | string | 资源类型 |
name |
是 | string | 资源名称 |
namespace |
否 | string | 命名空间 |
list-namespaces — 列出集群中的所有命名空间。
从源码看,资源查询能力建立在一张 resourceRegistry 注册表上(pkg/server/mcp_handlers.go),为每种资源类型注册了 list 与 get 两个回调;同时还有 resourceTypeAliases 别名表(pkg/server/mcp_handlers.go),因此 pods、svc、sts、ds、rs、cm、ing、pvc、pv 等缩写同样可用,normalizeResourceType 会统一转成规范形式并做校验。list 操作默认最多返回 100 条(DefaultListLimit),上限 1000(MaxListLimit),并支持通过 limit 参数调整。
调试与排障
get-logs — 获取 Pod 容器的日志
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
podName |
是 | string | Pod 名称 |
namespace |
是 | string | Pod 所在命名空间 |
container |
否 | string | 容器名称(多容器 Pod 时需要) |
previous |
否 | boolean | 获取上一个已终止容器的日志 |
tailLines |
否 | number | 从日志末尾返回的行数(默认 100) |
sinceSeconds |
否 | number | 仅返回最近 N 秒内的日志 |
list-events — 列出 Kubernetes 事件用于调试
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
namespace |
否 | string | 查询的命名空间 |
involvedObjectName |
否 | string | 按对象名称过滤 |
involvedObjectKind |
否 | string | 按对象类型过滤(如 Pod、Deployment) |
limit |
否 | number | 返回事件的最大数量(默认 100) |
值得强调的是,list-events 的 involvedObjectName / involvedObjectKind 过滤是在 API 请求层通过 fieldSelector(involvedObject.name、involvedObject.kind)下推到 Kubernetes API Server 执行的,而不是在本地对返回页做二次过滤(pkg/server/mcp_handlers.go)。配套测试 pkg/server/mcp_handlers_test.go 用一个模拟 K8s API 的 httptest 服务器专门验证了这一点:即使匹配事件位于 limit 截断页之外,fieldSelector 仍能正确命中。
Analyzer 管理
list-filters — 列出所有可用及已启用的 analyzer/过滤器。
其实现调用 analyzer.ListFilters()(pkg/analyzer/analyzer.go),返回三组列表:核心过滤器(coreAnalyzerMap,包括 Pod、Deployment、Service、Ingress、StatefulSet、Job、CronJob、Node、ConfigMap、DaemonSet、ReplicaSet、PersistentVolumeClaim、Validating/Mutating Webhook 等 14 项)、附加过滤器(additionalAnalyzerMap,包括 HPA、PDB、NetworkPolicy、Log、GatewayClass、Gateway、HTTPRoute、Storage、Security 及若干 OLM 相关项)以及已激活集成所提供的分析器;再结合 viper 中的 active_filters 返回当前激活列表。
add-filters — 添加过滤器以启用指定 analyzer
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
filters |
是 | array | 要添加的过滤器名列表(如 ['Pod', 'Service', 'Deployment']) |
remove-filters — 移除过滤器以禁用指定 analyzer
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
filters |
是 | array | 要移除的过滤器名列表 |
两者都会读写 viper 配置中的 active_filters 并调用 viper.WriteConfig() 持久化;重复添加已激活的过滤器会被去重并提示 All specified filters were already active。
集成管理
list-integrations — 列出可用集成(Prometheus、AWS、Keda、Kyverno 等)。实现通过 integration.NewIntegration() 与 IsActivate 返回每个集成的名称及当前激活状态(pkg/server/mcp_handlers.go)。
配置
config — 配置 K8sGPT 设置,包括自定义 analyzer 与缓存:
| 参数 | 说明 |
|---|---|
customAnalyzers |
自定义 analyzer 配置数组,每项含 name、connection.url、connection.port |
cache |
缓存配置,type 取 s3 / azure / gcs 之一,并按类型携带对应字段 |
- S3/GCS:
bucketName、region、endpoint(S3 自定义端点)、insecure(S3 是否使用不安全连接)、projectId(GCS 项目 ID) - Azure:
storageAccount(存储账户)、containerName(容器名)
实现中将请求转换为 AddConfigRequest 并交给 pkg/server/config 的 Handler.ApplyConfig 落地(pkg/server/mcp.go),成功返回 Successfully added configuration。
可用资源(Resources):只读访问集群信息
Resources 提供对集群信息的只读访问:
| 资源 | URI | 说明 |
|---|---|---|
| cluster-info | cluster-info |
获取 Kubernetes 集群信息(JSON,含 version、platform、gitVersion) |
| namespaces | namespaces |
列出集群中所有命名空间(JSON,含 count 与 namespaces 数组) |
| active-filters | active-filters |
获取当前激活的 analyzer/过滤器(JSON,含 activeFilters 与 count) |
三个资源的 handler 分别定义在 pkg/server/mcp.go,注册时声明为 application/json MIME 类型;其中 cluster-info 资源返回的数据比同名工具更丰富,会序列化 version.String()、platform 与 gitVersion 三个字段。
可用提示词(Prompts):引导式排障工作流
Prompts 提供引导式排障流程,注册逻辑见 pkg/server/mcp.go,提示文本模板在 pkg/server/mcp_prompts.go:
troubleshoot-pod — 交互式 Pod 排障工作流
| 参数 | 必填 | 说明 |
|---|---|---|
podName |
是 | 要排障的 Pod 名称 |
namespace |
是 | Pod 所在命名空间 |
生成的提示词引导 AI 依次执行:用 get-resource 查看 Pod 状态与条件、用 list-events 查看近期事件、用 get-logs 检查容器日志、处理多容器场景、对 CrashLoopBackOff 使用 previous=true 取旧日志、用 analyze(filters=['Pod'])做 AI 分析,并检查 ConfigMap、Secret、PVC 等关联资源。
troubleshoot-deployment — 交互式 Deployment 排障工作流
| 参数 | 必填 | 说明 |
|---|---|---|
deploymentName |
是 | Deployment 名称 |
namespace |
是 | Deployment 所在命名空间 |
提示词引导检查副本状态、ReplicaSet、通过 labelSelector 定位 Pod、事件、analyze(filters=['Deployment','Pod'])、镜像与拉取密钥、资源配额等。
troubleshoot-cluster — 通用集群排障工作流(无需参数),给出五步方法论:集群概览(cluster-info、list-namespaces、nodes)→ 资源分析(analyze + explain=true)→ 事件检查(list-events,关注 Warning/Error)→ 具体资源深挖(list/get-resource、get-logs)→ 配置核查(list-filters、list-integrations、config)。
完整调用示例:从查询到排障
以下示例均假设服务器已以 HTTP 模式运行在 localhost:8089。
示例 1:分析某个命名空间
curl -X POST http://localhost:8089/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "analyze",
"arguments": {
"namespace": "production",
"explain": "true"
}
}
}'
示例 2:列出 Pod
curl -X POST http://localhost:8089/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "list-resources",
"arguments": {
"resourceType": "pods",
"namespace": "default"
}
}
}'
示例 3:获取 Pod 日志
curl -X POST http://localhost:8089/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "get-logs",
"arguments": {
"podName": "nginx-abc123",
"namespace": "default",
"tail": "100"
}
}
}'
注意:源码中该参数实际命名为
tailLines(pkg/server/mcp.go),CLI 文档示例中的tail是较早命名,调用时应优先使用tailLines。
示例 4:读取资源
curl -X POST http://localhost:8089/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 4,
"method": "resources/read",
"params": {
"uri": "namespaces"
}
}'
示例 5:获取排障提示词
curl -X POST http://localhost:8089/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 5,
"method": "prompts/get",
"params": {
"name": "troubleshoot-pod",
"arguments": {
"podName": "nginx-abc123",
"namespace": "default"
}
}
}'
与 AI 助手的集成
Claude Desktop
将以下配置加入 claude_desktop_config.json:
{
"mcpServers": {
"k8sgpt": {
"command": "k8sgpt",
"args": ["serve", "--mcp"]
}
}
}
重启 Claude Desktop 后,工具选择器中即可看到 k8sgpt 的工具。README 中还介绍了另一种做法:先启动 k8sgpt serve --mcp,然后在 Claude Desktop 的 Settings → Integrations 中把 K8sGPT 添加为集成,MCP 服务器会被自动检测。连接成功后即可用自然语言下达指令,例如:
- "Analyze my Kubernetes cluster"
- "What's the health status of my cluster?"
- "Show me any issues in the default namespace"
自定义 MCP 客户端
任何 MCP 兼容客户端都可以连接 k8sgpt 服务器。基于 HTTP 的客户端:
- 启动服务器:
k8sgpt serve --mcp --mcp-http --mcp-port 8089 - 连接地址:
http://localhost:8089/mcp - 使用标准 MCP 方法:
tools/list、tools/call、resources/read、prompts/get
从测试代码(pkg/server/server_test.go)可以看到标准握手流程:先发 initialize(协议版本 2025-03-26,声明 tools/resources/prompts 能力),随后即可调用 tools/list 等方法。
Helm 方式部署(可选)
仓库的 charts/k8sgpt/values-mcp-example.yaml 提供了在集群内通过 Helm 部署 MCP 服务的示例,核心配置为:
deployment:
mcp:
enabled: true
port: "8089" # MCP 端口(默认 8089)
http: true # 启用 HTTP 模式
配合 helm install -f values-mcp-example.yaml 使用,可通过 service.type: ClusterIP 暴露 MCP 端点。
HTTP API 参考
端点
POST http://localhost:8089/mcp
Content-Type: application/json
请求格式
所有请求遵循 JSON-RPC 2.0 格式:
{
"jsonrpc": "2.0",
"id": 1,
"method": "method_name",
"params": {
...
}
}
发现方法
{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}
{"jsonrpc": "2.0", "id": 2, "method": "resources/list"}
{"jsonrpc": "2.0", "id": 3, "method": "prompts/list"}
工具调用
{
"jsonrpc": "2.0",
"id": 4,
"method": "tools/call",
"params": {
"name": "tool_name",
"arguments": {
"arg1": "value1",
"arg2": "value2"
}
}
}
资源访问
{
"jsonrpc": "2.0",
"id": 5,
"method": "resources/read",
"params": {
"uri": "resource_uri"
}
}
提示词访问
{
"jsonrpc": "2.0",
"id": 6,
"method": "prompts/get",
"params": {
"name": "prompt_name",
"arguments": {
"arg1": "value1"
}
}
}
响应格式
成功响应:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
...
}
}
错误响应:
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32600,
"message": "Error description"
}
}
进阶配置
自定义端口
k8sgpt serve --mcp --mcp-http --mcp-port 9000
指定特定后端
k8sgpt serve --mcp --backend openai
使用指定 kubeconfig
k8sgpt serve --mcp --kubeconfig ~/.kube/config
从源码看,serve 命令的 AI 后端解析支持 --backend 参数与环境变量 K8SGPT_BACKEND 的优先级:显式传入 --backend 时以参数为准,否则读取环境变量(cmd/serve/serve.go);AI Provider 的模型、密钥、baseURL 等也可通过 K8SGPT_MODEL、K8SGPT_PASSWORD、K8SGPT_BASEURL 等环境变量注入。
常见问题排查
连接问题
确认服务器正在运行:
curl http://localhost:8089/mcp
如果启动 MCP 后工具无法连接,按 README 建议依次检查:K8sGPT 是否以 MCP 模式运行、Kubernetes 集群是否可达、AI 后端是否配置正确,然后重启 K8sGPT 与客户端。
权限问题
确保 kubeconfig 对集群有合适的访问权限:
kubectl cluster-info
工具调用报错
列出可用工具以核对工具名与参数名:
curl -X POST http://localhost:8089/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'
工具的参数名以 JSON Schema 为准(例如 get-logs 使用 tailLines 而非 tail),资源类型支持缩写(svc、sts、pvc 等),不支持的资源类型会返回错误并附上受支持的类型清单。
延伸阅读
- 本文档原文:MCP.md
- MCP 服务器实现:pkg/server/mcp.go、pkg/server/mcp_handlers.go、pkg/server/mcp_prompts.go
- 集成测试:pkg/server/mcp_handlers_test.go、pkg/server/server_test.go
- 入口命令与参数定义:cmd/serve/serve.go
- 分析引擎:pkg/analysis/analysis.go
- Analyzer 过滤器清单:pkg/analyzer/analyzer.go
- Helm 部署示例:charts/k8sgpt/values-mcp-example.yaml