Kubernetes MCP Server

Kubernetes MCP 服务

一个 Kubernetes 模型上下文协议（MCP）服务，提供通过标准化接口与 Kubernetes 集群交互的工具。

托管部署

Fr点AI 提供托管部署。

功能

• API 资源发现：获取 Kubernetes 集群中所有可用的 API 资源。
• 资源列表：列出任意类型的资源，并可按命名空间和标签筛选。
• 资源详情：获取特定 Kubernetes 资源的详细信息。
• 资源描述：获取 Kubernetes 资源的完整描述，类似于 kubectl describe。
• Pod 日志：检索特定 Pod 的日志（可选指定容器；未指定时检索所有容器的日志）。
• 节点指标：获取特定节点的资源使用指标。
• Pod 指标：获取特定 Pod 的 CPU 和内存指标。
• 事件列表：列出命名空间内或特定资源的事件。
• 资源创建/更新：根据 YAML 或 JSON 清单创建新的 Kubernetes 资源或更新现有资源。
• 资源删除：根据提供的命名空间和类型，删除 Kubernetes 集群中的资源。
• 标准化接口：使用 MCP 协议实现一致的工具交互。
• 灵活配置：支持不同的 Kubernetes 上下文和资源范围。
• 多种模式：为命令行工具运行于 stdio 模式，为 Web 应用运行于 sse 或 streamable-http 模式；使用 --readonly 可确保不更改集群。
• 安全性：在 Docker 容器中以非 root 用户身份运行，增强安全性。

前提条件

• Go 1.23 或更高版本
• 可访问 Kubernetes 集群
• 已配置适当集群访问权限的 kubectl

安装

1. 克隆仓库：

   git clone https://github.com/reza-gholizade/k8s-mcp-server.git
   cd k8s-mcp-server
   

2. 安装依赖项：

   go mod download
   

3. 构建服务：

   go build -o k8s-mcp-server .
   

使用方法

启动服务

服务支持三种运行模式，可通过命令行标志或环境变量配置。

Stdio 模式（用于 CLI 集成）

此模式使用标准输入/输出进行通信。

./k8s-mcp-server --mode stdio

也可以使用环境变量：

SERVER_MODE=stdio ./k8s-mcp-server

SSE 模式（用于 Web 应用）

此模式会启动支持服务器发送事件的 HTTP 服务。

HTTP 传输需要 Bearer 令牌，默认监听回环地址：

MCP_AUTH_TOKEN="$(openssl rand -hex 32)" ./k8s-mcp-server --mode sse

指定端口：

MCP_AUTH_TOKEN="your-random-secret" ./k8s-mcp-server --mode sse --port 9090

也可以使用环境变量：

SERVER_MODE=sse SERVER_PORT=9090 MCP_AUTH_TOKEN="your-random-secret" ./k8s-mcp-server

Streamable-HTTP 模式（用于 Web 应用）

此模式会启动支持 streamable-http 传输的 HTTP 服务，并遵循 MCP 规范。

默认（端口 8080）：

MCP_AUTH_TOKEN="your-random-secret" ./k8s-mcp-server --mode streamable-http

指定端口：

MCP_AUTH_TOKEN="your-random-secret" ./k8s-mcp-server --mode streamable-http --port 9090

也可以使用环境变量：

SERVER_MODE=streamable-http SERVER_PORT=9090 MCP_AUTH_TOKEN="your-random-secret" ./k8s-mcp-server

服务将在 http://localhost:8080/mcp（或指定端口）上提供。

如果未指定模式，服务默认使用 stdio。HTTP 模式默认绑定到 127.0.0.1。只有在确实需要网络访问时，才设置 SERVER_HOST=0.0.0.0（或 --host 0.0.0.0），并在每个 MCP 请求中发送 Authorization: Bearer <token>。 浏览器客户端也必须通过以逗号分隔的 MCP_ALLOWED_ORIGINS 值显式允许。

未进行身份验证的 /healthz 端点可用于容器健康检查； 它不会提供 MCP 功能。

Kubernetes 身份验证

服务支持多种身份验证方法，并按以下优先级顺序依次尝试：

1. 通过环境变量提供 Kubeconfig 内容

可以通过 KUBECONFIG_DATA 环境变量提供完整的 kubeconfig 文件内容：

export KUBECONFIG_DATA="$(cat ~/.kube/config)"
./k8s-mcp-server

当你希望避免挂载文件，或在文件访问受限的环境中运行时，这种方式很有用。

2. API 服务 URL 和令牌

你可以使用 Kubernetes API 服务 URL 和 bearer 令牌进行身份验证：

export KUBERNETES_SERVER="https://kubernetes.example.com:6443"
export KUBERNETES_TOKEN="your-bearer-token-here"
./k8s-mcp-server

TLS 配置的可选环境变量：

• KUBERNETES_CA_CERT：CA 证书内容（采用 base64 编码或 PEM 格式）
• KUBERNETES_CA_CERT_PATH：CA 证书文件的路径
• KUBERNETES_INSECURE：设为 "true" 可跳过 TLS 验证（不建议用于生产环境）

使用 CA 证书的示例：

export KUBERNETES_SERVER="https://kubernetes.example.com:6443"
export KUBERNETES_TOKEN="your-bearer-token-here"
export KUBERNETES_CA_CERT_PATH="/path/to/ca.crt"
./k8s-mcp-server

3. 集群内身份验证（服务账户）

在 Kubernetes 集群内运行时，服务会自动检测并使用 /var/run/secrets/kubernetes.io/serviceaccount/token 中的服务账户令牌。这是将服务作为集群内 Pod 运行的推荐方式。

部署示例：

apiVersion: v1
kind: ServiceAccount
metadata:
  name: k8s-mcp-server-sa
  namespace: default
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: k8s-mcp-server-role
rules:
  - apiGroups: [""]
    resources: ["*"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
  - apiGroups: ["apps"]
    resources: ["*"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
  # Add more rules as needed for your use case
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: k8s-mcp-server-rb
subjects:
  - kind: ServiceAccount
    name: k8s-mcp-server-sa
    namespace: default
roleRef:
  kind: ClusterRole
  name: k8s-mcp-server-role
  apiGroup: rbac.authorization.k8s.io
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: k8s-mcp-server
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: k8s-mcp-server
  template:
    metadata:
      labels:
        app: k8s-mcp-server
    spec:
      serviceAccountName: k8s-mcp-server-sa
      containers:
        - name: k8s-mcp-server
          image: ginnux/k8s-mcp-server:latest
          ports:
            - containerPort: 8080
          env:
            - name: SERVER_MODE
              value: "sse"
            - name: SERVER_PORT
              value: "8080"

4. Kubeconfig 文件路径（默认）

如果以上方法均不可用，服务会回退到使用 kubeconfig 文件：

• 使用通过 --kubeconfig 标志（如果已实现）或 KUBECONFIG 环境变量提供的路径
• 如果两者均未指定，则默认使用 ~/.kube/config

# Using default ~/.kube/config
./k8s-mcp-server

# Using custom kubeconfig path
export KUBECONFIG=/path/to/your/kubeconfig
./k8s-mcp-server

注意： 服务会根据可用的环境变量和文件系统，自动检测要使用的身份验证方法。你无需显式配置身份验证方法——服务会按上述优先级顺序使用第一个可用的方法。

只读模式

服务支持只读模式，可禁用所有写入操作，让你能够更安全地探索和监控 Kubernetes 集群，避免修改集群。

使用 --read-only 标志启用只读模式：

./k8s-mcp-server --read-only

你可以将只读模式与任何服务模式结合使用：

# Read-only with stdio mode
./k8s-mcp-server --mode stdio --read-only

# Read-only with SSE mode
./k8s-mcp-server --mode sse --read-only

# Read-only with streamable-http mode
./k8s-mcp-server --mode streamable-http --read-only

启用只读模式后，将禁用以下工具：

• createResource（创建／更新 Kubernetes 资源）
• helmInstall（安装 Helm chart）
• helmUpgrade（升级 Helm chart）
• helmUninstall（卸载 Helm chart）
• helmRollback（回滚 Helm 发布）
• helmRepoAdd（添加 Helm 仓库）

其他所有只读操作仍可使用，包括列出资源、获取日志、查看指标和检查 Helm 发布。

工具类别标志

你可以使用以下标志，有选择地禁用整个工具类别：

禁用 Kubernetes 工具：

./k8s-mcp-server --no-k8s

禁用 Helm 工具：

./k8s-mcp-server --no-helm

与其他标志组合使用：

# Read-only mode with only Kubernetes tools (no Helm)
./k8s-mcp-server --read-only --no-helm

# Read-only mode with only Helm tools (no Kubernetes)
./k8s-mcp-server --read-only --no-k8s

# SSE mode with only Kubernetes tools
./k8s-mcp-server --mode sse --no-helm

注意： 不能同时使用 --no-k8s 和 --no-helm，因为这样会导致没有可用工具。如果同时提供这两个标志，服务将报错并退出。

启用 --no-k8s 后，将禁用所有 Kubernetes 工具：

• getAPIResources、listResources、getResource、describeResource
• getPodsLogs、getNodeMetrics、getPodMetrics、getEvents
• createResource（未处于只读模式时）

启用 --no-helm 后，将禁用所有 Helm 工具：

• helmList、helmGet、helmHistory、helmRepoList
• helmInstall、helmUpgrade、helmUninstall、helmRollback、helmRepoAdd（未处于只读模式时）

使用 Docker 镜像

你也可以使用 Docker Hub 上预构建的 Docker 镜像运行服务。

1. 拉取镜像：

   docker pull ginnux/k8s-mcp-server:latest
   

   你可以将 latest 替换为特定版本标签（例如 1.0.0）。

2. 运行容器：

   注意： 服务支持多种身份验证方式。你可以挂载 kubeconfig 文件（如下所示），也可以使用环境变量进行身份验证（请参阅上文的 Kubernetes 身份验证 部分）。

   • SSE 模式（镜像的默认行为）：

     docker run -p 8080:8080 -v ~/.kube/config:/home/appuser/.kube/config:ro ginnux/k8s-mcp-server:latest
     

     这会将容器的 8080 端口映射到主机上的 8080 端口，并将 Kubernetes 配置以只读方式挂载到非 root 用户的主目录。服务将在 http://localhost:8080 上提供。镜像默认以 sse 模式在端口 8080 上运行。

   • Streamable-HTTP 模式：

     docker run -p 8080:8080 -v ~/.kube/config:/home/appuser/.kube/config:ro ginnux/k8s-mcp-server:latest --mode streamable-http
     

     这会以 streamable-http 模式运行服务。服务将在 http://localhost:8080/mcp 上提供。

   • Stdio 模式：

     docker run -i --rm -v ~/.kube/config:/home/appuser/.kube/config:ro ginnux/k8s-mcp-server:latest --mode stdio
     

     -i 标志对于交互式 stdio 通信很重要。--rm 会在容器退出后清理容器。

   • SSE 模式下使用自定义端口：

     docker run -p 9090:9090 -v ~/.kube/config:/home/appuser/.kube/config:ro ginnux/k8s-mcp-server:latest --mode sse --port 9090
     

   • Streamable-HTTP 模式下使用自定义端口：

     docker run -p 9090:9090 -v ~/.kube/config:/home/appuser/.kube/config:ro ginnux/k8s-mcp-server:latest --mode streamable-http --port 9090
     

   • 替代方案：挂载整个 .kube 目录：

     docker run -p 8080:8080 -v ~/.kube:/home/appuser/.kube:ro ginnux/k8s-mcp-server:latest
     

   • 使用环境变量进行身份验证（无需挂载文件）：

     # 使用环境变量中的 kubeconfig 内容
     docker run -p 8080:8080 \
       -e KUBECONFIG_DATA="$(cat ~/.kube/config)" \
       ginnux/k8s-mcp-server:latest
     
     # 或使用 API 服务器 URL 和令牌
     docker run -p 8080:8080 \
       -e KUBERNETES_SERVER="https://kubernetes.example.com:6443" \
       -e KUBERNETES_TOKEN="your-token-here" \
       -e KUBERNETES_CA_CERT_PATH="/path/to/ca.crt" \
       -v /path/to/ca.crt:/path/to/ca.crt:ro \
       ginnux/k8s-mcp-server:latest
     

使用 Docker Compose

创建一个 docker-compose.yml 文件：

选项 1：使用 kubeconfig 文件（传统方式）：

version: '3.8'
services:
  k8s-mcp-server:
    image: ginnux/k8s-mcp-server:latest # Or a specific version
    container_name: k8s-mcp-server
    ports:
      - "8080:8080" # Host:Container, adjust if using a different SERVER_PORT
    volumes:
      - ~/.kube:/home/appuser/.kube:ro # Mount kubeconfig read-only to non-root user home
    environment:
      - KUBECONFIG=/home/appuser/.kube/config
      - SERVER_MODE=sse # Can be 'stdio', 'sse', or 'streamable-http'
      - SERVER_PORT=8080 # Port for SSE/streamable-http modes
    # command: ["--read-only"] # Uncomment this line to enable read-only mode
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

选项 2：使用环境变量（无需挂载文件）：

version: '3.8'
services:
  k8s-mcp-server:
    image: ginnux/k8s-mcp-server:latest
    container_name: k8s-mcp-server
    ports:
      - "8080:8080"
    environment:
      - KUBECONFIG_DATA=${KUBECONFIG_DATA} # Set this in your .env file or shell
      # Or use API server and token:
      # - KUBERNETES_SERVER=https://kubernetes.example.com:6443
      # - KUBERNETES_TOKEN=${KUBERNETES_TOKEN}
      - SERVER_MODE=sse
      - SERVER_PORT=8080
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

注意： 要启用只读模式，请使用选项 1 所示的 command 覆盖。对于 stdio 模式，你可能需要调整 ports，添加 stdin_open: true 和 tty: true，并可能需要覆盖命令。

然后启动：

docker compose up -d

查看日志：docker compose logs -f k8s-mcp-server。

安全注意事项

为增强安全性，Docker 镜像以非 root 用户（UID 为 1001 的 appuser）运行：

• 应用程序二进制文件位于 /usr/local/bin/k8s-mcp-server
• kubeconfig 应挂载到 /home/appuser/.kube/config
• 已启用运行状况检查以监控容器状态
• 容器仅包含最少的依赖项（仅 ca-certificates 和 curl）

除非设置了 MCP_AUTH_TOKEN，否则 SSE 和 streamable HTTP 均采用默认拒绝策略。切勿在未启用身份验证的情况下公开 HTTP 传输。对于本地 MCP 客户端，优先使用 stdio；在可能的情况下使用 --read-only，并且仅向服务的 Kubernetes 身份授予所需的 RBAC 权限。会话 ID 不是身份验证凭据。将可远程访问的部署置于 TLS 和经过身份验证的反向代理之后，并为基于浏览器的客户端配置 MCP_ALLOWED_ORIGINS。

发起 API 调用（SSE/Streamable-HTTP 模式）

服务器以 SSE 或 streamable-http 模式运行后，你可以向其 HTTP 端点发送 JSON-RPC 调用：

curl -X POST -H "Content-Type: application/json" -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "getAPIResources",
    "arguments": {
      "includeNamespaceScoped": true,
      "includeClusterScoped": true
    }
  }
}' http://localhost:8080/

你也可以检查运行状况：

curl -f http://localhost:8080/

可用工具

1. getAPIResources

获取 Kubernetes 集群中所有可用的 API 资源。

参数：

• includeNamespaceScoped（boolean，可选）：是否包含命名空间范围的资源（默认为 true）。
• includeClusterScoped（boolean，可选）：是否包含集群范围的资源（默认为 true）。

示例：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "getAPIResources",
    "arguments": {
      "includeNamespaceScoped": true,
      "includeClusterScoped": true
    }
  }
}

2. listResources

列出指定资源类型的所有实例。

参数：

• Kind（string，必填）：要列出的资源类型（例如，“Pod”、“Deployment”）。
• namespace（string，可选）：要从中列出资源的命名空间。若省略，则列出所有命名空间中的资源（适用于命名空间范围的资源，且受 RBAC 限制）。
• labelSelector（string，可选）：按标签选择器筛选资源（例如，“app=nginx,env=prod”）。

示例：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "listResources",
    "arguments": {
      "Kind": "Pod",
      "namespace": "default",
      "labelSelector": "app=nginx"
    }
  }
}

3. getResource

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

参数：

• kind（string，必填）：要获取的资源类型（例如，“Pod”、“Deployment”）。
• name（string，必填）：要获取的资源名称。
• namespace（string，可选）：资源所属的命名空间（命名空间范围的资源必填）。

示例：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "getResource",
    "arguments": {
      "kind": "Pod",
      "name": "nginx-pod",
      "namespace": "default"
    }
  }
}

4. describeResource

描述 Kubernetes 集群中的资源，类似于 kubectl describe。

参数：

• Kind（string，必填）：要描述的资源类型（例如，“Pod”、“Deployment”）。
• name（string，必填）：要描述的资源名称。
• namespace（string，可选）：资源所属的命名空间（命名空间范围的资源必填）。

示例：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "describeResource",
    "arguments": {
      "Kind": "Pod",
      "name": "nginx-pod",
      "namespace": "default"
    }
  }
}

5. getPodsLogs

获取特定 Pod 的日志。

参数：

• Name（string，必填）：Pod 的名称。
• namespace（string，必填）：Pod 所属的命名空间。
• containerName（string，可选）：Pod 中特定容器的名称。若省略：
  • 如果 Pod 只有一个容器，则获取该容器的日志。
  • 如果 Pod 有多个容器，则获取并拼接所有容器的日志。

示例：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "getPodsLogs",
    "arguments": {
      "Name": "my-app-pod-12345",
      "namespace": "production",
      "containerName": "main-container"
    }
  }
}

6. getNodeMetrics

获取特定节点的资源使用指标。

参数：

• Name（string，必填）：节点的名称。

示例：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "getNodeMetrics",
    "arguments": {
      "Name": "worker-node-1"
    }
  }
}

7. getPodMetrics

获取特定 Pod 的 CPU 和内存指标。

参数：

• namespace（string，必填）：Pod 所属的命名空间。
• podName（string，必填）：Pod 的名称。

示例：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "getPodMetrics",
    "arguments": {
      "namespace": "default",
      "podName": "my-app-pod-67890"
    }
  }
}

8. getEvents

获取特定命名空间或资源的事件。

参数：

• namespace (string, optional)：要获取事件的命名空间。如果省略，则会考虑所有命名空间中的事件（受 RBAC 限制）。
• resourceName (string, optional)：要筛选事件的特定资源名称（例如 Pod 名称）。
• resourceKind (string, optional)：特定资源的类型（例如 "Pod"），仅在提供 resourceName 时使用。

示例（命名空间事件）：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "getEvents",
    "arguments": {
      "namespace": "default"
    }
  }
}

示例（资源事件）：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "getEvents",
    "arguments": {
      "namespace": "production",
      "resourceName": "my-app-pod-12345",
      "resourceKind": "Pod"
    }
  }
}

9. createOrUpdateResource

根据 JSON 清单创建新资源或更新现有资源。

参数：

• manifest (string, required)：资源的 JSON 清单。
• namespace (string, optional)：创建或更新资源所在的命名空间。如果清单中包含命名空间，可使用此参数覆盖它。如果未提供此参数，且清单中也未指定命名空间，则可能会使用 "default"，也可能根据资源类型报错。

示例：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "createResource",
    "arguments": {
      "kind": "Deployment",
      "namespace": "default",
      "manifest": "{\"apiVersion\":\"apps/v1\",\"kind\":\"Deployment\",\"metadata\":{\"name\":\"nginx-deployment\"},\"spec\":{\"replicas\":1,\"selector\":{\"matchLabels\":{\"app\":\"nginx\"}},\"template\":{\"metadata\":{\"labels\":{\"app\":\"nginx\"}},\"spec\":{\"containers\":[{\"name\":\"nginx\",\"image\":\"nginx:latest\"}]}}}}"
    }
  }
}

10. createResourceYAML

根据 YAML 清单创建新资源或更新现有资源。此工具专为 YAML 输入优化，能够更好地处理 YAML 解析问题。

参数：

• yamlManifest (string, required)：资源的 YAML 清单。
• namespace (string, optional)：创建或更新资源所在的命名空间。如果清单中包含命名空间，可使用此参数覆盖它。如果未提供此参数，且清单中也未指定命名空间，则可能会使用 "default"，也可能根据资源类型报错。
• kind (string, optional)：资源的类型。如果未提供，则会从 YAML 清单中推断。

示例：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "createResourceYAML",
    "arguments": {
      "namespace": "default",
      "yamlManifest": "apiVersion: v1\nkind: Pod\nmetadata:\n  name: my-new-pod\nspec:\n  containers:\n  - name: nginx\n    image: nginx:latest"
    }
  }
}

11. rolloutRestart

触发支持 spec.template.metadata.annotations 的 Kubernetes 资源的滚动重启。这包括 Deployment、DaemonSet、StatefulSet、Job 等资源。

参数：

• kind (string, required)：资源类型（例如 "Deployment"、"StatefulSet"）。
• name：（string, required）：要重启的资源名称。
• namespace (string, required for namespaced resources)：资源所在的命名空间。

示例（StatefulSet）：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "rolloutRestart",
    "arguments": {
      "kind": "StatefulSet",
      "name": "redis-cluster-01",
      "namespace": "default"
    }
  }
}

示例（Deployment）：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "rolloutRestart",
    "arguments": {
      "kind": "Deployment",
      "name": "my-app-deployment",
      "namespace": "default"
    }
  }
}

12. deleteResource

从 Kubernetes 集群中删除指定资源。

参数：

• kind (string, required)：要删除的资源类型。
• name (string, required)：要删除的资源名称。
• namespace (string, optional)：资源所在的命名空间（命名空间级资源必填）。

示例：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "deleteResource",
    "arguments": {
      "kind": "Pod",
      "name": "my-pod",
      "namespace": "default"
    }
  }
}

13. getIngresses

从 Kubernetes 集群中获取 Ingress 资源。 你可以按主机筛选 Ingress。如果未提供主机，则返回所有 Ingress。

参数：

• host (string, optional)：用于筛选 Ingress 的主机。如果省略，则包含所有 Ingress。

示例：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "getIngresses",
    "arguments": {
      "host": "example.com"
    }
  }
}

Helm 操作

14. helmInstall

将 Helm chart 安装到 Kubernetes 集群。

参数：

• releaseName (string, required)：Helm release 的名称
• chartName (string, required)：Helm chart 的名称或路径
• namespace (string, optional)：release 所在的 Kubernetes 命名空间（默认为 "default"）
• repoURL (string, optional)：Helm 仓库 URL
• values (object, optional)：要覆盖的 chart 配置值

示例：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "helmInstall",
    "arguments": {
      "releaseName": "my-nginx",
      "chartName": "bitnami/nginx",
      "namespace": "web",
      "repoURL": "https://charts.bitnami.com/bitnami",
      "values": {
        "replicaCount": 3,
        "service": {
          "type": "LoadBalancer"
        }
      }
    }
  }
}

15. helmUpgrade

升级现有的 Helm 发布版本。

参数：

• releaseName（字符串，必需）：Helm 发布版本的名称
• chartName（字符串，必需）：Helm Chart 的名称或路径
• namespace（字符串，必需）：发布版本所在的 Kubernetes 命名空间（默认为 "default"）
• repoURL（字符串，可选）：Helm 仓库 URL；对于本地 Chart 路径或可从已配置仓库解析的 Chart，可省略
• values（对象，必需）：要覆盖的 Chart 值 示例：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "helmUpgrade",
    "arguments": {
      "releaseName": "my-nginx",
      "chartName": "nginx",
      "namespace": "web",
      "repoURL": "https://charts.bitnami.com/bitnami",
      "values": {
        "replicaCount": 2,
        "service": {
          "type": "NodePort"
        }
      }
    }
  }
}

16. helmList

列出集群中或特定命名空间内的所有 Helm 发布版本。

17. helmGet

获取特定 Helm 发布版本的详细信息。

18. helmHistory

获取 Helm 发布版本的历史记录。

19. helmRollback

将 Helm 发布版本回滚到之前的修订版本。

20. helmUninstall

从 Kubernetes 集群中卸载 Helm 发布版本。

添加新工具

1. 定义工具：在 tools/tools.go 中，定义一个返回 mcp.Tool 结构体的函数。该结构体包含工具名称、描述以及输入和输出架构。
2. 实现处理函数：在 handlers/handlers.go 中创建处理函数。该函数接收 *k8s.Client 作为参数，并返回一个签名为 func(context.Context, mcp.ToolInput) (mcp.ToolOutput, error) 的函数。这个内部函数将包含工具的逻辑。
3. 注册工具：在 main.go 中，使用 s.AddTool(tools.YourToolDefinitionFunction(), handlers.YourToolHandlerFunction(client)) 将新工具添加到 MCP 服务实例中。

贡献

欢迎贡献！有关如何为此项目做贡献的详情，请参阅 CONTRIBUTING.md。

许可证

[email protected]

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

VS Code 集成

快速设置

自动安装（推荐）

macOS/Linux：

curl -sSL https://raw.githubusercontent.com/reza-gholizade/k8s-mcp-server/main/scripts/install-vscode-config.sh | bash

Windows（PowerShell）：

iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/reza-gholizade/k8s-mcp-server/main/scripts/install-vscode-config.ps1'))

手动安装

1. 在 VS Code 中安装 MCP 扩展：

   code --install-extension modelcontextprotocol.mcp
   

2. 添加到 VS Code 的 settings.json：

   打开 VS Code 设置（Cmd/Ctrl + ,）→ 打开 Settings JSON → 添加：

   macOS/Linux：

   {
     "mcp.mcpServers": {
       "k8s-mcp-server": {
         "command": "k8s-mcp-server",
         "args": ["--mode", "stdio"],
         "env": {
           "KUBECONFIG": "${env:HOME}/.kube/config"
         }
       }
     }
   }
   

   只读模式（出于安全考虑，推荐使用）：

   {
     "mcp.mcpServers": {
       "k8s-mcp-server": {
         "command": "k8s-mcp-server",
         "args": ["--mode", "stdio", "--read-only"],
         "env": {
           "KUBECONFIG": "${env:HOME}/.kube/config"
         }
       }
     }
   }
   

   仅使用 Kubernetes 工具：

   {
     "mcp.mcpServers": {
       "k8s-mcp-server": {
         "command": "k8s-mcp-server",
         "args": ["--mode", "stdio", "--no-helm"],
         "env": {
           "KUBECONFIG": "${env:HOME}/.kube/config"
         }
       }
     }
   }
   

   仅使用 Helm 工具：

   {
     "mcp.mcpServers": {
       "k8s-mcp-server": {
         "command": "k8s-mcp-server",
         "args": ["--mode", "stdio", "--no-k8s"],
         "env": {
           "KUBECONFIG": "${env:HOME}/.kube/config"
         }
       }
     }
   }
   

   只读模式且仅使用 Kubernetes 工具：

   {
     "mcp.mcpServers": {
       "k8s-mcp-server": {
         "command": "k8s-mcp-server",
         "args": ["--mode", "stdio", "--read-only", "--no-helm"],
         "env": {
           "KUBECONFIG": "${env:HOME}/.kube/config"
         }
       }
     }
   }
   

   Windows：

   {
     "mcp.mcpServers": {
       "k8s-mcp-server": {
         "command": "k8s-mcp-server.exe",
         "args": ["--mode", "stdio"],
         "env": {
           "KUBECONFIG": "${env:USERPROFILE}/.kube/config"
         }
       }
     }
   }
   

3. 确保二进制文件位于 PATH 中：

   从 releases page 下载相应的二进制文件，并将其添加到系统 PATH 中。

4. 重启 VS Code

在 VS Code 中使用

配置完成后，你可以在 VS Code 中使用 Kubernetes MCP 服务，搭配 Claude 或其他兼容 MCP 的工具：

1. 打开 VS Code
2. 访问 Claude（或其他启用 MCP 的 AI 助手）
3. 使用自然语言与 Kubernetes 集群交互：
   • “列出 default 命名空间中的所有 Pod”
   • “显示 pod nginx-123 的日志”
   • “获取 worker-node-1 的 CPU 使用情况”
   • “描述名为 my-app 的 Deployment”

配置选项

你可以通过修改设置来自定义配置：

{
  "mcp.mcpServers": {
    "k8s-mcp-server": {
      "command": "k8s-mcp-server",
      "args": ["--mode", "stdio"],
      "env": {
        "KUBECONFIG": "/path/to/your/kubeconfig",
        "KUBERNETES_CONTEXT": "your-context-name"
      }
    }
  }
}

故障排除

• 找不到二进制文件：确保 k8s-mcp-server 位于 PATH 中
• Kubernetes 连接问题：确认 KUBECONFIG 路径正确
• 权限错误：确保 kubeconfig 具有所需的 RBAC 权限
• 扩展未加载：更改配置后重启 VS Code