k8s-MCP服务器

Name: k8s-MCP服务器
Author: reza-gholizade

作者：reza-gholizade119 星标更新：2025-11-19

安装使用来源：spider==github.com

项目介绍

Kubernetes MCP Server

一个提供工具通过标准化接口与Kubernetes集群交互的Kubernetes Model Context Protocol (MCP)服务器。

功能

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

前提条件

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

安装

克隆仓库：

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

安装依赖项：
```
go mod download
```
构建服务器：
```
go build -o k8s-mcp-server main.go
```

使用

启动服务器

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

Stdio模式（用于CLI集成）

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

./k8s-mcp-server --mode stdio

或者使用环境变量：

SERVER_MODE=stdio ./k8s-mcp-server

SSE模式（用于Web应用程序）

此模式启动具有Server-Sent Events支持的HTTP服务器。

默认（端口8080）：

./k8s-mcp-server --mode sse

指定端口：

./k8s-mcp-server --mode sse --port 9090

或者使用环境变量：

SERVER_MODE=sse SERVER_PORT=9090 ./k8s-mcp-server

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

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

默认（端口8080）：

./k8s-mcp-server --mode streamable-http

指定端口：

./k8s-mcp-server --mode streamable-http --port  9090

或者使用环境变量：

SERVER_MODE=streamable-http SERVER_PORT=9090 ./k8s-mcp-server

服务器将在http://localhost:8080/mcp（或您指定的端口）上可用。

如果未指定模式，默认为端口8080上的SSE。

Kubernetes认证

服务器支持多种认证方法，按以下优先顺序尝试：

1. 来自环境变量的kubeconfig内容

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

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

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

2. API服务器URL和Token

您可以使用Kubernetes API服务器URL和bearer token进行认证：

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的服务账户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"]
  # 根据您的用例添加更多规则
---
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

# 使用默认的~/.kube/config
./k8s-mcp-server

# 使用自定义kubeconfig路径
export KUBECONFIG=/path/to/your/kubeconfig
./k8s-mcp-server

注意：服务器会根据可用的环境变量和文件系统自动检测要使用的认证方法。您不需要显式配置认证方法——它将按照上面列出的优先顺序使用第一个可用的方法。

只读模式

服务器支持只读模式，该模式禁用了所有写操作，提供了一种更安全的方式来探索和监控您的Kubernetes集群，而不会带来更改的风险。

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

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

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

# 只读与stdio模式
./k8s-mcp-server --mode stdio --read-only

# 只读与SSE模式
./k8s-mcp-server --mode sse --read-only

# 只读与streamable-http模式
./k8s-mcp-server --mode streamable-http --read-only

当启用只读模式时，以下工具被禁用：

createResource（Kubernetes资源的创建/更新）
helmInstall（Helm图表安装）
helmUpgrade（Helm图表升级）
helmUninstall（Helm图表卸载）
helmRollback（Helm发布回滚）
helmRepoAdd（Helm存储库添加）

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

工具类别标志

您可以使用这些标志选择性地禁用整个类别的工具：

禁用Kubernetes工具：

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

禁用Helm工具：

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

与其他标志组合：

# 只读模式，仅Kubernetes工具（无Helm）
./k8s-mcp-server --read-only --no-helm

# 只读模式，仅Helm工具（无Kubernetes）
./k8s-mcp-server --read-only --no-k8s

# SSE模式，仅Kubernetes工具
./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镜像来运行服务器。

拉取镜像：
```
docker pull ginnux/k8s-mcp-server:latest
```
您可以用特定版本标签替换latest（例如，1.0.0）。

运行容器：

注意：服务器支持多种认证方法。您可以挂载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上可用。镜像默认在端口8080上使用sse模式。

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和token
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 # 或特定版本
    container_name: k8s-mcp-server
    ports:
      - "8080:8080" # 主机:容器，调整如果您使用了不同的SERVER_PORT
    volumes:
      - ~/.kube:/home/appuser/.kube:ro # 将kubeconfig以只读方式挂载到非root用户的家目录
    environment:
      - KUBECONFIG=/home/appuser/.kube/config
      - SERVER_MODE=sse # 可以是'stdio'，'sse'或'streamable-http'
      - SERVER_PORT=8080 # SSE/streamable-http模式的端口
    # command: ["--read-only"] # 取消注释此行以启用只读模式
    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} # 在您的.env文件或shell中设置这个
      # 或使用API服务器和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: 20s
      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）

发起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/

k8s-MCP服务器

项目介绍

Kubernetes MCP Server

功能

前提条件

安装

使用

启动服务器

Stdio模式（用于CLI集成）

SSE模式（用于Web应用程序）

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

Kubernetes认证

1. 来自环境变量的kubeconfig内容

2. API服务器URL和Token

3. 集群内认证（服务账户）

4. kubeconfig文件路径（默认）

只读模式

工具类别标志

使用Docker镜像

使用Docker Compose

安全注意事项

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

可用工具

1. `getAPIResources`

k8s-MCP服务器

项目介绍

Kubernetes MCP Server

功能

前提条件

安装

使用

启动服务器

Stdio模式（用于CLI集成）

SSE模式（用于Web应用程序）

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

Kubernetes认证

1. 来自环境变量的kubeconfig内容

2. API服务器URL和Token

3. 集群内认证（服务账户）

4. kubeconfig文件路径（默认）

只读模式

工具类别标志

使用Docker镜像

使用Docker Compose

安全注意事项

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

可用工具

1. getAPIResources

1. `getAPIResources`