K8sGPT MCP 服务器实战指南:用 Model Context Protocol 让 AI 助手直接运维 Kubernetes 集群

原创2026-10-15 14:30:461,947 阅读
文章标签:云原生运维AI 应用MCP 服务

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 的客户端:

  1. 启动服务器:k8sgpt serve --mcp --mcp-http --mcp-port 8089
  2. 连接地址:http://localhost:8089/mcp
  3. 使用标准 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 等),不支持的资源类型会返回错误并附上受支持的类型清单。

延伸阅读

登录后查看全文
k8sgpt