kubernetes-mcp

🚀 Kubernetes MCP Server

Kubernetes MCP Server 是一个模型上下文协议（MCP）服务器，它为调试和检查提供了对 Kubernetes 资源的安全、只读访问。该服务器在设计时充分考虑了安全性，可在不具备修改功能的情况下，提供全面的集群可见性。

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

🚀 快速开始

前提条件

• 拥有有效的 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 .

✨ 主要特性

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

📦 安装指南

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"
}

// 获取暂存环境中的 Pod 日志
{
  "name": "api-server",
  "context": "staging-cluster",
  "namespace": "api"
}

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

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

可自动发现并与集群中的任何 CRD 协作。只需在 list_resources 或 describe_resource 工具中使用 CRD 的 Kind 名称即可。

🔍 智能资源发现

使用 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 文件。