Kubernetes MCP服务器

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

特性

API资源发现：获取Kubernetes集群中所有可用的API资源。
资源列表：列出具有可选命名空间和标签筛选的任何类型的资源。
资源详细信息：获取有关特定Kubernetes资源的详细信息。
资源描述：获取Kubernetes资源的全面描述，类似于 kubectl describe.
Pod日志：从特定Pod中检索日志（可选地从特定容器中检索，如果未指定，则从所有容器中检索）。
节点度量：获取特定节点的资源使用指标。
Pod指标：获取特定Pod的CPU和内存指标。
活动列表：列出命名空间内或特定资源的事件。
资源创建/更新：创建新的Kubernetes资源或从YAML或JSON清单更新现有资源。
标准化接口：使用MCP协议进行一致的工具交互。
灵活的配置：支持不同的Kubernetes上下文和资源范围。
多种模式：磨合 stdio CLI工具的模式或 sse web应用程序的模式。
安全：在Docker容器中以非root用户身份运行，以增强安全性。

先决条件

转到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

用法

启动服务器

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

标准模式（用于CLI集成）

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

./k8s-mcp-server --mode stdio

或者使用环境变量：

SERVER_MODE=stdio ./k8s-mcp-server

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

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

默认值（端口8080）：

./k8s-mcp-server --mode sse

指定端口：

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

或者使用环境变量：

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

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

使用Docker镜像

您还可以使用Docker Hub中的预构建Docker映像运行服务器。

拉取图像：

   docker pull ginnux/k8s-mcp-server:latest

您可以替换 latest 具有特定版本标签（例如。， 1.0.0).

运行容器：

- 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.

- 标准模式：

     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

- 替代方法：挂载整个.kube目录：

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

使用Docker Compose

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

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 # Default, can be 'stdio'
      - SERVER_PORT=8080 # Port for SSE mode
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    # To run in stdio mode with docker-compose, you might need to adjust 'ports',
    # add 'stdin_open: true' and 'tty: true', and potentially override the command.
    # For example, to force stdio mode:
    # command: ["--mode", "stdio"]
    # stdin_open: true
    # tty: true

然后开始：

docker compose up -d

要查看日志，请执行以下操作： docker compose logs -f k8s-mcp-server.

安全考虑

Docker镜像以非root用户身份运行(appuser UID 1001）以增强安全性：

应用程序二进制文件位于 /usr/local/bin/k8s-mcp-server
kubeconfig应该挂载到 /home/appuser/.kube/config
启用健康检查以监视容器状态
容器包含最小的依赖项（仅限ca证书和curl）

进行API调用（SSE模式）

一旦服务器在SSE模式下运行，您就可以对其HTTP端点进行JSON-RPC调用：

curl -X POST -H "Content-Type: application/json" -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getAPIResources",
  "params": {
    "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": "getAPIResources",
  "params": {
    "arguments": {
      "includeNamespaceScoped": true,
      "includeClusterScoped": true
    }
  }
}

2. `listResources`

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

参数：

Kind （string，必填）：要列出的资源类型（例如，“Pod”、“Deployment”）。
namespace （string，可选）：用于列出资源的命名空间。如果省略，则列出命名空间资源的所有命名空间（受RBAC约束）。
labelSelector （字符串，可选）：按标签选择器过滤资源（例如，“app=nginx，env=prod”）。

例子：

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

3. `getResource`

检索特定资源的详细信息。

参数：

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

例子：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getResource",
  "params": {
    "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": "describeResource",
  "params": {
    "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": "getPodsLogs",
  "params": {
    "arguments": {
      "Name": "my-app-pod-12345",
      "namespace": "production",
      "containerName": "main-container"
    }
  }
}

6. `getNodeMetrics`

检索特定节点的资源使用指标。

参数：

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

例子：

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

7. `getPodMetrics`

检索特定pod的CPU和内存指标。

参数：

namespace （string，必填）：pod的命名空间。
podName （string，必填）：pod的名称。

例子：

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

8. `getEvents`

检索特定命名空间或资源的事件。

参数：

namespace （string，可选）：从中获取事件的命名空间。如果省略，则考虑来自所有命名空间的事件（受RBAC约束）。
resourceName （string，可选）：要过滤事件的特定资源的名称（例如Pod名称）。
resourceKind （string，可选）：特定资源的类型（例如“Pod”），如果 resourceName 提供。

示例（命名空间事件）：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getEvents",
  "params": {
    "arguments": {
      "namespace": "default"
    }
  }
}

示例（资源事件）：

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

9. `createOrUpdateResource`

从YAML或JSON清单创建新资源或更新现有资源。

参数：

manifest （必填）：资源的YAML/JSON清单。这可以作为字符串或结构化JSON对象提供。
namespace （string，可选）：创建/更新资源的命名空间。如果清单包含命名空间，则可以使用此参数覆盖它。如果没有提供并且清单没有指定命名空间，则可能会假定为“默认”，或者根据资源类型，这可能是一个错误。

例子：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "createOrUpdateResource",
  "params": {
    "arguments": {
      "namespace": "default",
      "manifest": {
        "apiVersion": "v1",
        "kind": "Pod",
        "metadata": { "name": "my-new-pod" },
        "spec": {
          "containers": [
            { "name": "nginx", "image": "nginx:latest" }
          ]
        }
      }
    }
  }
}

Helm操作

10. `helmInstall`

将Helm chart安装到Kubernetes集群。

参数：

releaseName （string，必填）：Helm版本的名称
chartName （string，必填）：Helm图表的名称或路径
namespace （string，可选）：版本的Kubernetes命名空间（默认为“default”）
repoURL （字符串，可选）：Helm存储库URL
values （对象，可选）：要在图表中覆盖的值

例子：

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

11. `helmUpgrade`

升级现有的Helm版本。

12. `helmUninstall`

从Kubernetes集群卸载Helm版本。

13. `helmList`

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

14. `helmGet`

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

15. `helmHistory`

获取Helm发布的历史记录。

16. `helmRollback`

将Helm版本回滚到以前的版本。

发展

项目结构

.
├── .github/workflows/  # GitHub Actions workflows
│   └── docker-build-push.yml
├── handlers/           # Tool handlers and tool definitions
│   └── handlers.go
├── pkg/                # Internal packages
│   └── k8s/            # Kubernetes client implementation
├── tools/              # MCP Tool definitions
│   └── tools.go
├── main.go             # Server entry point
├── go.mod              # Go module definition
├── go.sum              # Go module checksums
├── Dockerfile          # Docker build definition
└── docker-compose.yml  # Docker Compose definition (example)

添加新工具

定义工具：In tools/tools.go，定义一个返回 mcp.Tool 结构。这包括工具的名称、描述和输入/输出模式。
实现处理程序：In handlers/handlers.go，创建一个处理函数。此功能需要 *k8s.Client 作为参数，返回一个带有签名的函数 func(context.Context, mcp.ToolInput) (mcp.ToolOutput, error)。此内部函数将包含工具的逻辑。
注册工具：In main.go，使用以下命令将新工具添加到MCP服务器实例中 s.AddTool(tools.YourToolDefinitionFunction(), handlers.YourToolHandlerFunction(client)).

贡献

欢迎投稿！请看贡献.md 了解如何为这个项目做出贡献的详细信息。

许可证

gholizade.net@gmail.com

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

VS代码集成

快速设置

自动安装（推荐）

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'))

手动安装

在VS代码中安装MCP扩展：

   code --install-extension modelcontextprotocol.mcp

添加到您的VS代码设置.json：

打开VS代码设置（Cmd/Ctrl+，）→ 打开设置JSON→ Add:

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.exe",
         "args": ["--mode", "stdio"],
         "env": {
           "KUBECONFIG": "${env:USERPROFILE}/.kube/config"
         }
       }
     }
   }

确保二进制文件在PATH中：

从下载相应的二进制文件发布页面并将其添加到系统PATH中。

重新启动VS代码

VS代码中的用法

配置后，您可以在VS Code中使用Kubernetes MCP服务器与Claude或其他MCP兼容工具：

打开VS代码
访问Claude（或其他启用MCP的AI助手）
使用自然语言与Kubernetes集群交互：

- “列出默认命名空间中的所有Pod” - “显示pod nginx-123的日志” - “获取worker-node-1的CPU使用率” - “描述名为我的应用程序的部署”

配置选项

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

{
  "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 在你的路径中
Kubernetes连接问题：验证您的 KUBECONFIG 路径正确
权限错误：确保您的kubeconfig具有必要的RBAC权限
扩展未加载：配置更改后重新启动VS代码

Ginnux K8s MCP Server

快速接入

详细介绍

Kubernetes MCP服务器

特性

先决条件

安装

用法

启动服务器

标准模式（用于CLI集成）

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

使用Docker镜像

使用Docker Compose

安全考虑

进行API调用（SSE模式）

可用工具

1. getAPIResources

2. listResources

3. getResource

4. describeResource

5. getPodsLogs

6. getNodeMetrics

7. getPodMetrics

8. getEvents

9. createOrUpdateResource

Helm操作

10. helmInstall

11. helmUpgrade

12. helmUninstall

13. helmList

14. helmGet

15. helmHistory

16. helmRollback

发展

项目结构

添加新工具

贡献

许可证

VS代码集成

快速设置

自动安装（推荐）

手动安装

VS代码中的用法

配置选项

故障排除

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

1. `getAPIResources`

2. `listResources`

3. `getResource`

4. `describeResource`

5. `getPodsLogs`

6. `getNodeMetrics`

7. `getPodMetrics`

8. `getEvents`

9. `createOrUpdateResource`

10. `helmInstall`

11. `helmUpgrade`

12. `helmUninstall`

13. `helmList`

14. `helmGet`

15. `helmHistory`

16. `helmRollback`