Kubernetes MCP 服务器

https://github.com/user-attachments/assets/89df70b0-65d1-461c-b4ab-84b2087136fa

这是一个模型上下文协议（MCP）服务器，提供对 Kubernetes 资源的安全只读访问，用于调试和检查。考虑到安全性，它提供了全面的集群可见性，但没有修改能力。

功能

• 🔒 只读安全：安全地检查 Kubernetes 资源，没有修改能力
• 🎯 自定义资源定义支持：与集群中的任何自定义资源定义无缝工作
• 🌐 多集群支持：在不同的 Kubernetes 上下文之间无缝切换
• 🔍 智能发现：通过 API 组子字符串查找资源（例如，“flux”用于 FluxCD，“argo”用于 ArgoCD）
• ⚡ 高性能：高效查询资源，具有过滤和分页功能
• 🛠️ 全面工具集：
  • list_resources：列出并筛选 Kubernetes 资源，带有高级选项
  • describe_resource：获取特定资源的详细信息
  • get_pod_logs：检索带有复杂过滤功能的 Pod 日志
  • list_events：列出并筛选 Kubernetes 事件，用于调试和监控
  • list_contexts：从 kubeconfig 列出所有可用的 Kubernetes 上下文

🚀 快速开始

前提条件

• 具有有效 kubeconfig 文件的 Kubernetes 集群访问权限
• Go 1.24+（用于从源代码构建）

安装选项

选项 1：使用 Go 安装（推荐）

go install github.com/kkb0318/kubernetes-mcp@latest

二进制文件将在 $GOPATH/bin/kubernetes-mcp（如果未设置 GOPATH，则为 $HOME/go/bin/kubernetes-mcp）中可用。

选项 2：从源代码构建

git clone https://github.com/kkb0318/kubernetes-mcp.git
cd kubernetes-mcp
go build -o kubernetes-mcp .

⚙️ 配置

MCP 服务器设置

将服务器添加到您的 MCP 配置中：

基本配置

自动使用 ~/.kube/config：

{
  "mcpServers": {
    "kubernetes": {
      "command": "/path/to/kubernetes-mcp"
    }
  }
}

自定义 Kubeconfig

{
  "mcpServers": {
    "kubernetes": {
      "command": "/path/to/kubernetes-mcp",
      "env": {
        "KUBECONFIG": "/path/to/your/kubeconfig"
      }
    }
  }
}

注意：用实际的二进制路径替换 /path/to/kubernetes-mcp。

独立使用

# 默认 kubeconfig (~/.kube/config)
./kubernetes-mcp

# 自定义 kubeconfig 路径
KUBECONFIG=/path/to/your/kubeconfig ./kubernetes-mcp

重要：确保您有权访问要检查的 Kubernetes 资源。

🛠️ 可用工具

list_resources

列出并筛选 Kubernetes 资源，带有高级功能。

参数	类型	描述
context	可选	kubeconfig 中的 Kubernetes 上下文名称（留空表示当前上下文）
kind	必需	资源类型（Pod、Deployment、Service 等）或“all”以进行发现
groupFilter	可选	通过 API 组子字符串筛选项目特定资源
namespace	可选	目标命名空间（默认为所有命名空间）
labelSelector	可选	通过标签筛选（例如，“app=nginx”）
fieldSelector	可选	通过字段筛选（例如，“metadata.name=my-pod”）
limit	可选	返回的最大资源数
timeoutSeconds	可选	请求超时时间（默认：30 秒）
showDetails	可选	返回完整的资源对象而不是摘要

示例：

// 列出带有标签选择器的 Pod
{
  "kind": "Pod",
  "namespace": "default",
  "labelSelector": "app=nginx"
}

// 列出来自特定集群上下文的 Pod
{
  "kind": "Pod",
  "context": "production-cluster",
  "namespace": "default"
}

// 发现 FluxCD 资源
{
  "kind": "all",
  "groupFilter": "flux"
}

describe_resource

获取特定 Kubernetes 资源的详细信息。

参数	类型	描述
context	可选	kubeconfig 中的 Kubernetes 上下文名称（留空表示当前上下文）
kind	必需	资源类型（Pod、Deployment 等）
name	必需	资源名称
namespace	可选	目标命名空间

示例：

{
  "kind": "Pod",
  "name": "nginx-pod",
  "namespace": "default"
}

get_pod_logs

带有复杂过滤选项的 Pod 日志检索。

参数	类型	描述
context	可选	kubeconfig 中的 Kubernetes 上下文名称（留空表示当前上下文）
name	必需	Pod 名称
namespace	可选	Pod 命名空间（默认为“default”）
container	可选	特定容器名称
tail	可选	从末尾开始的行数（默认：100）
since	可选	持续时间，如“5s”，“2m”，“3h”
sinceTime	可选	RFC3339 时间戳
timestamps	可选	在输出中包含时间戳
previous	可选	获取来自先前容器实例的日志

示例：

{
  "name": "nginx-pod",
  "namespace": "default",
  "tail": 50,
  "since": "5m",
  "timestamps": true
}

list_events

带有高级过滤选项的 Kubernetes 事件列表，用于调试和监控。

参数	类型	描述
context	可选	kubeconfig 中的 Kubernetes 上下文名称（留空表示当前上下文）
namespace	可选	目标命名空间（留空表示所有命名空间）
object	可选	通过对象名称筛选（例如，pod 名称、deployment 名称）
eventType	可选	通过事件类型筛选：“Normal”或“Warning”（不区分大小写）
reason	可选	通过事件原因筛选（例如，“Pulled”，“Failed”，“FailedScheduling”）
since	可选	持续时间，如“5s”，“2m”，“1h”
sinceTime	可选	RFC3339 时间戳（例如，“2025-06-20T10:00:00Z”）
limit	可选	返回的最大事件数（默认：100）
timeoutSeconds	可选	请求超时时间（默认：30 秒）

示例：

// 列出最近的警告事件
{
  "eventType": "Warning",
  "since": "30m"
}

// 列出特定 pod 的事件
{
  "object": "nginx-pod",
  "namespace": "default"
}

// 列出失败调度事件
{
  "reason": "FailedScheduling",
  "limit": 50
}

list_contexts

从您的 kubeconfig 文件中列出所有可用的 Kubernetes 上下文。

参数： 无 - 此工具不需要参数。

示例响应：

{
  "contexts": [
    {
      "name": "production-cluster",
      "is_current": false
    },
    {
      "name": "staging-cluster", 
      "is_current": true
    },
    {
      "name": "development-cluster",
      "is_current": false
    }
  ],
  "current_context": "staging-cluster",
  "total": 3
}

使用场景： 适用于多集群工作流程，需要：

• 发现可用的 Kubernetes 上下文
• 识别当前活动的上下文
• 在多个集群上计划操作

🌟 高级功能

🌐 多集群支持

使用上下文切换无缝处理多个 Kubernetes 集群：

• 上下文参数：所有工具现在都支持一个可选的 context 参数来指定要查询的集群
• 自动发现：使用现有的 kubeconfig 文件并自动发现可用的上下文
• 默认上下文：当未指定上下文时，使用 kubeconfig 中的当前上下文
• 缓存连接：通过连接缓存有效地管理到多个集群的连接

多集群示例：

// 查询生产集群
{
  "kind": "Pod",
  "context": "production-cluster",
  "namespace": "default"
}

// 获取来自 staging 环境的日志
{
  "name": "api-server",
  "context": "staging-cluster",
  "namespace": "api"
}

// 比较跨环境的资源（使用多次调用）
{
  "kind": "Deployment",
  "context": "production-cluster",
  "namespace": "app"
}

🎯 自定义资源定义（CRD）支持

自动发现并处理集群中的任何 CRD。只需使用 CRD 的 Kind 名称与 list_resources 或 describe_resource 工具。

🔍 智能资源发现

使用 groupFilter 参数通过 API 组子字符串发现资源：

过滤器	发现	示例
"flux"	FluxCD 资源	HelmReleases, Kustomizations, GitRepositories
"argo"	ArgoCD 资源	Applications, AppProjects, ApplicationSets
"istio"	Istio 资源	VirtualServices, DestinationRules, Gateways
"cert-manager"	cert-manager 资源	Certificates, Issuers, ClusterIssuers

🔒 安全与保障

构建时将安全性作为主要关注点：

• ✅ 只读访问 - 不创建、修改或删除资源
• ✅ 生产安全 - 在生产环境中安全使用
• ✅ 最小权限 - 只需访问集群资源的读取权限
• ✅ 无破坏性操作 - 无法损害您的集群

---

🤝 贡献

我们欢迎贡献！请确保所有更改保持服务器的只读性质，并包括适当的测试。

📄 许可证

本项目根据 MIT 许可证发布 - 查看 LICENSE 文件了解详情。