reza-gholizade
服务介绍
Kubernetes MCP 服务器
一个 Kubernetes 模型上下文协议 (MCP) 服务器，提供通过标准化接口与 Kubernetes 集群交互的工具。
特性
- API 资源发现：获取 Kubernetes 集群中所有可用的 API 资源。
- 资源列表：列出任何类型的资源，并可选地进行命名空间和标签过滤。
- 资源详情：获取特定 Kubernetes 资源的详细信息。
- 资源描述：获取 Kubernetes 资源的全面描述，类似于
kubectl describe。 - Pod 日志：从特定 Pod 中检索日志（可选地从特定容器或所有容器）。
- 节点指标：获取特定节点的资源使用指标。
- Pod 指标：获取特定 Pod 的 CPU 和内存指标。
- 事件列表：列出命名空间内的事件或特定资源的事件。
- 资源创建/更新：从 YAML 或 JSON 清单文件创建新的 Kubernetes 资源或更新现有资源。
- 标准化接口：使用 MCP 协议以实现一致的工具交互。
- 灵活配置：支持不同的 Kubernetes 上下文和资源范围。
- 多种模式：可以在
stdio模式下运行以供 CLI 工具使用，或在sse模式下运行以供 Web 应用程序使用。
前提条件
- Go 1.20 或更高版本
- 访问 Kubernetes 集群
- 配置了适当集群访问权限的
kubectl
安装
-
克隆仓库：
bash
git clone https://github.com/reza-gholizade/k8s-mcp-server.git
cd k8s-mcp-server -
安装依赖项：
bash
go mod download -
构建服务器：
bash
go build -o k8s-mcp-server main.go
使用
启动服务器
服务器可以以两种模式运行，可以通过命令行标志或环境变量进行配置。
Stdio 模式（用于 CLI 集成）
此模式使用标准输入/输出进行通信。
bash
./k8s-mcp-server --mode stdio
或者使用环境变量：
bash
SERVER_MODE=stdio ./k8s-mcp-server
SSE 模式（用于 Web 应用程序）
此模式启动一个支持 Server-Sent Events 的 HTTP 服务器。
默认（端口 8080）：
bash
./k8s-mcp-server --mode sse
指定端口：
bash
./k8s-mcp-server --mode sse --port 9090
或者使用环境变量：
bash
SERVER_MODE=sse SERVER_PORT=9090 ./k8s-mcp-server
如果没有指定模式，默认为 SSE 模式并使用端口 8080。
使用 Docker 镜像
您也可以使用来自 Docker Hub 的预构建 Docker 镜像来运行服务器。
-
拉取镜像：
bash
docker pull ginnux/k8s-mcp-server:latest可以将
latest替换为特定版本标签（例如1.0.0）。 -
运行容器：
-
SSE 模式（镜像的默认行为）：
bash
docker run -p 8080:8080 -v ~/.kube/config:/root/.kube/config:ro ginnux/k8s-mcp-server:latest这会将容器的 8080 端口映射到主机的 8080 端口，并以只读方式挂载您的 Kubernetes 配置。服务器将在
http://localhost:8080可用。镜像默认为sse模式并在端口8080上运行。 -
Stdio 模式：
bash
docker run -i --rm -v ~/.kube/config:/root/.kube/config:ro ginnux/k8s-mcp-server:latest --mode stdio-i标志对于交互式的 stdio 通信很重要。--rm在退出后清理容器。 -
SSE 模式的自定义端口：
bash
docker run -p 9090:9090 -v ~/.kube/config:/root/.kube/config:ro ginnux/k8s-mcp-server:latest --mode sse --port 9090
-
使用 Docker Compose
创建一个 docker-compose.yml 文件：
yaml
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:/root/.kube:ro # 以只读方式挂载 kubeconfig
environment:
- KUBECONFIG=/root/.kube/config
- SERVER_MODE=sse # 默认，可以是 stdio
- SERVER_PORT=8080 # SSE 模式的端口
restart: unless-stopped
# 若要在 stdio 模式下使用 docker-compose，可能需要调整 ports，
# 添加 stdin_open: true 和 tty: true，并可能覆盖命令。
# 例如，强制使用 stdio 模式：
# command: ["--mode", "stdio"]然后开始执行：
bash
docker compose up -d
要查看日志：docker compose logs -f k8s-mcp-server。
发起API调用（SSE模式）
一旦服务器以SSE模式运行，你可以向其HTTP端点发起JSON-RPC调用（例如，/或/rpc，具体取决于mcp-go库的SSE服务器实现）：
bash
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/
（注意：使用SSE服务器时，JSON-RPC over HTTP的确切端点可能依赖于mcp-go库的版本。如果/不起作用，请尝试/rpc。）
可用工具
1. getAPIResources
检索Kubernetes集群中所有可用的API资源。
参数：
includeNamespaceScoped(布尔型, 可选): 是否包含命名空间范围内的资源（默认为true）。includeClusterScoped(布尔型, 可选): 是否包含集群范围内的资源（默认为true）。
示例：
json
{
"jsonrpc": "2.0",
"id": 1,
"method": "getAPIResources",
"params": {
"arguments": {
"includeNamespaceScoped": true,
"includeClusterScoped": true
}
}
}
2. listResources
列出特定类型资源的所有实例。
参数：
Kind(字符串, 必需): 要列出的资源种类（例如，“Pod”，“Deployment”）。namespace(字符串, 可选): 列出资源的命名空间。如果省略，则对于命名空间范围内的资源将跨所有命名空间列出（受RBAC限制）。labelSelector(字符串, 可选): 按标签选择器过滤资源（例如，“app=nginx,env=prod”）。
示例：
json
{
"jsonrpc": "2.0",
"id": 1,
"method": "listResources",
"params": {
"arguments": {
"Kind": "Pod",
"namespace": "default",
"labelSelector": "app=nginx"
}
}
}
3. getResource
获取特定资源的详细信息。
参数：
kind(字符串, 必需): 要获取的资源种类（例如，“Pod”，“Deployment”）。name(字符串, 必需): 要获取的资源名称。namespace(字符串, 可选): 资源所在的命名空间（对于命名空间范围内的资源是必需的）。
示例：
json
{
"jsonrpc": "2.0",
"id": 1,
"method": "getResource",
"params": {
"arguments": {
"kind": "Pod",
"name": "nginx-pod",
"namespace": "default"
}
}
}
4. describeResource
描述Kubernetes集群中的一个资源，类似于kubectl describe。
参数：
Kind(字符串, 必需): 要描述的资源种类（例如，“Pod”，“Deployment”）。name(字符串, 必需): 要描述的资源名称。namespace(字符串, 可选): 资源所在的命名空间（对于命名空间范围内的资源是必需的）。
示例：
json
{
"jsonrpc": "2.0",
"id": 1,
"method": "describeResource",
"params": {
"arguments": {
"Kind": "Pod",
"name": "nginx-pod",
"namespace": "default"
}
}
}
5. getPodsLogs
检索特定pod的日志。
参数：
Name(字符串, 必需): pod的名称。namespace(字符串, 必需): pod所在的命名空间。containerName(字符串, 可选): pod内的特定容器名称。如果省略：- 如果pod有一个容器，则获取该容器的日志。
- 如果pod有多个容器，则获取所有容器的日志并将其连接起来。
示例：
json
{
"jsonrpc": "2.0",
"id": 1,
"method": "getPodsLogs",
"params": {
"arguments": {
"Name": "my-app-pod-12345",
"namespace": "production",
"containerName": "main-container"
}
}
}
6. getNodeMetrics
检索特定节点的资源使用情况指标。
参数：
Name(字符串, 必需): 节点的名称。
示例：
json
{
"jsonrpc": "2.0",
"id": 1,
"method": "getNodeMetrics",
"params": {
"arguments": {
"Name": "worker-node-1"
}
}
}#### 7. getPodMetrics
检索特定 Pod 的 CPU 和内存指标。
参数:
namespace(字符串, 必需): Pod 所在的命名空间。podName(字符串, 必需): Pod 的名称。
示例:
json
{
"jsonrpc": "2.0",
"id": 1,
"method": "getPodMetrics",
"params": {
"arguments": {
"namespace": "default",
"podName": "my-app-pod-67890"
}
}
}
8. getEvents
检索特定命名空间或资源的事件。
参数:
namespace(字符串, 可选): 获取事件的命名空间。如果省略，则考虑所有命名空间中的事件（受 RBAC 限制）。resourceName(字符串, 可选): 特定资源的名称（例如，Pod 名称），用于过滤事件。resourceKind(字符串, 可选): 如果提供了resourceName，则为特定资源的类型（例如，“Pod”）。
示例（命名空间事件）:
json
{
"jsonrpc": "2.0",
"id": 1,
"method": "getEvents",
"params": {
"arguments": {
"namespace": "default"
}
}
}
示例（资源事件）:
json
{
"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 清单。namespace(字符串, 可选): 创建/更新资源的命名空间。如果清单中包含命名空间，可以使用此参数覆盖它。如果没有提供且清单未指定命名空间，则可能假设为“default”，或者根据资源类型可能会报错。
示例:
json
{
"jsonrpc": "2.0",
"id": 1,
"method": "createOrUpdateResource",
"params": {
"arguments": {
"namespace": "default",
"manifest": "apiVersion: v1\nkind: Pod\nmetadata:\n name: my-new-pod\nspec:\n containers:\n - name: nginx\n image: nginx:latest"
}
}
}
开发
项目结构
.
├── .github/workflows/ # GitHub Actions 工作流
│ └── docker-build-push.yml
├── handlers/ # 工具处理程序和工具定义
│ └── handlers.go
├── pkg/ # 内部包
│ └── k8s/ # Kubernetes 客户端实现
├── tools/ # MCP 工具定义
│ └── tools.go
├── main.go # 服务器入口点
├── go.mod # Go 模块定义
├── go.sum # Go 模块校验和
├── Dockerfile # Docker 构建定义
└── docker-compose.yml # Docker Compose 定义（示例）
添加新工具
- 定义工具: 在
tools/tools.go中，定义一个返回mcp.Tool结构的函数。这包括工具的名称、描述和输入/输出模式。 - 实现处理程序: 在
handlers/handlers.go中，创建一个处理程序函数。该函数接受*k8s.Client作为参数，并返回一个具有签名func(context.Context, mcp.ToolInput) (mcp.ToolOutput, error)的函数。这个内部函数将包含你的工具逻辑。 - 注册工具: 在
main.go中，使用s.AddTool(tools.YourToolDefinitionFunction(), handlers.YourToolHandlerFunction(client))将你的新工具添加到 MCP 服务器实例中。
贡献
欢迎贡献！请参阅 CONTRIBUTING.md 了解如何为该项目做出贡献的详细信息。
许可证
本项目采用 MIT 许可证 - 详情请参见 LICENSE 文件。
