MKP - Model Kontext Protocol Server for Kubernetes

MKP - Kubernetes 的 Model Context Protocol 服务

MKP 是一个面向 Kubernetes 的 Model Context Protocol（MCP）服务，允许由大模型驱动的应用与 Kubernetes 集群交互。它通过 MCP 协议提供列出和应用 Kubernetes 资源的工具。

功能

• 列出 Kubernetes API 服务端支持的资源
• 列出集群级资源
• 列出命名空间级资源
• 获取资源及其子资源（包括状态、扩缩容、日志等）
• 应用（创建或更新）集群级资源
• 应用（创建或更新）命名空间级资源
• 在 Pod 中执行命令，并控制超时时间
• 使用 API Machinery 的非结构化客户端实现通用且可插拔的功能
• 内置速率限制，防止过多 API 调用

为什么选择 MKP？

作为面向 Kubernetes 的 Model Context Protocol 服务，MKP 具有多项关键优势：

原生 Go 实现

• 使用与 Kubernetes 本身相同的语言构建
• 具备出色的服务端应用性能
• 提供强类型安全性和并发支持
• 与 Kubernetes 库无缝集成

直接集成 API

• 直接使用 Kubernetes API machinery，无需外部依赖
• 不依赖 kubectl、helm 或其他 CLI 工具
• 直接与 Kubernetes API 服务端通信
• 降低开销并提升可靠性

通用资源支持

• 通过非结构化客户端支持任何 Kubernetes 资源类型
• 无需硬编码资源架构或专用处理程序
• 自动支持自定义资源定义（CRD）
• 面向未来的 Kubernetes 新资源

极简设计

• 专注于核心 Kubernetes 资源操作
• 代码库整洁、易于维护，职责划分清晰
• 轻量级，依赖项极少
• 易于理解、扩展和贡献

可用于生产环境的架构

• 专为生产环境中的可靠性和性能而设计
• 具备完善的错误处理和资源管理
• 内置速率限制，防止过多 API 调用
• 设计易于测试，并包含全面的单元测试
• 遵循 Kubernetes 开发最佳实践

前提条件

• Go 1.24 或更高版本
• Kubernetes 集群和 kubeconfig
• 用于运行任务的 Task

安装

1. 克隆仓库：

   git clone https://github.com/StacklokLabs/mkp.git
   cd mkp
   

2. 安装依赖项：

   task install
   

3. 构建服务：

   task build
   

使用方法

运行服务

使用默认 kubeconfig 运行服务：

task run

使用指定的 kubeconfig 运行服务：

KUBECONFIG=/path/to/kubeconfig task run-with-kubeconfig

在指定端口上运行服务：

MCP_PORT=9091 task run

使用 ToolHive 运行

MKP 可通过 ToolHive 作为 Model Context Protocol（MCP）服务运行，从而简化 MCP 服务的部署和管理。

有关如何通过 ToolHive UI、CLI 或 Kubernetes operator 设置 MKP 的详细说明，请参阅 ToolHive 文档。

MCP 工具

MKP 服务提供以下 MCP 工具：

get_resource

获取 Kubernetes 资源或其子资源。

参数：

• resource_type（必需）：资源类型（集群级或命名空间级）
• group：API 组（例如，apps、networking.k8s.io）
• version（必需）：API 版本（例如，v1、v1beta1）
• resource（必需）：资源名称（例如，deployments、services）
• namespace：命名空间（命名空间级资源必需）
• name（必需）：要获取的资源名称
• subresource：要获取的子资源（例如，status、scale、logs）
• parameters：请求的可选参数（参见下方示例）

示例：

{
  "name": "get_resource",
  "arguments": {
    "resource_type": "namespaced",
    "group": "apps",
    "version": "v1",
    "resource": "deployments",
    "namespace": "default",
    "name": "nginx-deployment",
    "subresource": "status"
  }
}

使用参数获取特定容器日志的示例：

{
  "name": "get_resource",
  "arguments": {
    "resource_type": "namespaced",
    "group": "",
    "version": "v1",
    "resource": "pods",
    "namespace": "default",
    "name": "my-pod",
    "subresource": "logs",
    "parameters": {
      "container": "my-container",
      "sinceSeconds": "3600",
      "timestamps": "true",
      "limitBytes": "102400"
    }
  }
}

Pod 日志的可用参数：

• container：指定要获取日志的容器
• previous：获取前一个容器实例的日志（true/false）
• sinceSeconds：仅返回相对时间范围（以秒为单位）内的较新日志
• sinceTime：仅返回指定时间之后的日志（RFC3339 格式）
• timestamps：在每行日志中包含时间戳（true/false）
• limitBytes：返回的最大字节数
• tailLines：从日志末尾返回的行数

默认情况下，Pod 日志仅返回最后 100 行和 32KB，以避免超出大模型的上下文窗口。可使用上述参数覆盖这些默认值。

常规资源的可用参数：

• resourceVersion：指定后，显示该特定版本的资源

list_resources

列出特定类型的 Kubernetes 资源。

参数：

• resource_type（必需）：资源类型（集群级或命名空间级）
• group：API 组（例如，apps、networking.k8s.io）
• version（必需）：API 版本（例如，v1、v1beta1）
• resource（必需）：资源名称（例如，deployments、services）
• namespace：命名空间（命名空间级资源必需）
• label_selector：用于筛选资源的 Kubernetes 标签选择器（可选）
• include_annotations：是否在输出中包含注释（默认值： true）
• exclude_annotation_keys：要从输出中排除的注释键列表 （支持使用 * 通配符）
• include_annotation_keys：要包含在输出中的注释键列表（如果 指定，则仅包含这些键）

注释筛选

list_resources 工具提供强大的注释筛选功能，可控制元数据输出大小，并避免大型注释（例如 GPU 节点注释）导致的截断问题。

基本用法：

{
  "name": "list_resources",
  "arguments": {
    "resource_type": "namespaced",
    "group": "apps",
    "version": "v1",
    "resource": "deployments",
    "namespace": "default"
  }
}

排除特定注释（适用于 GPU 节点）：

{
  "name": "list_resources",
  "arguments": {
    "resource_type": "clustered",
    "group": "",
    "version": "v1",
    "resource": "nodes",
    "exclude_annotation_keys": [
      "nvidia.com/*",
      "kubectl.kubernetes.io/last-applied-configuration"
    ]
  }
}

仅包含特定注释：

{
  "name": "list_resources",
  "arguments": {
    "resource_type": "namespaced",
    "group": "",
    "version": "v1",
    "resource": "pods",
    "namespace": "default",
    "include_annotation_keys": ["app", "version", "prometheus.io/scrape"]
  }
}

完全禁用注释以获得最佳性能：

{
  "name": "list_resources",
  "arguments": {
    "resource_type": "namespaced",
    "group": "",
    "version": "v1",
    "resource": "pods",
    "namespace": "default",
    "include_annotations": false
  }
}

注释筛选规则：

• 默认情况下，会排除 kubectl.kubernetes.io/last-applied-configuration，以避免输出大型配置数据
• exclude_annotation_keys 支持使用 * 通配符模式（例如， nvidia.com/* 会排除所有 NVIDIA 注释）
• 指定 include_annotation_keys 时，该参数优先，仅包含指定的注释
• 设置 include_annotations: false 会从输出中完全移除所有注释
• 通配符模式仅支持在键的末尾使用 *（例如， nvidia.com/*）

apply_resource

应用（创建或更新）Kubernetes 资源。

参数：

• resource_type（必需）：要应用的资源类型（集群级或 命名空间级）
• group：API 组（例如，apps、networking.k8s.io）
• version（必需）：API 版本（例如，v1、v1beta1）
• resource（必需）：资源名称（例如，deployments、services）
• namespace：命名空间（命名空间级资源必需）
• manifest（必需）：资源清单

示例：

{
  "name": "apply_resource",
  "arguments": {
    "resource_type": "namespaced",
    "group": "apps",
    "version": "v1",
    "resource": "deployments",
    "namespace": "default",
    "manifest": {
      "apiVersion": "apps/v1",
      "kind": "Deployment",
      "metadata": {
        "name": "nginx-deployment",
        "namespace": "default"
      },
      "spec": {
        "replicas": 3,
        "selector": {
          "matchLabels": {
            "app": "nginx"
          }
        },
        "template": {
          "metadata": {
            "labels": {
              "app": "nginx"
            }
          },
          "spec": {
            "containers": [
              {
                "name": "nginx",
                "image": "nginx:latest",
                "ports": [
                  {
                    "containerPort": 80
                  }
                ]
              }
            ]
          }
        }
      }
    }
  }
}

post_resource

向 Kubernetes 资源或其子资源发送请求，特别适用于在 Pod 中执行命令。

参数：

• resource_type（必需）：要发送请求的资源类型（集群级或命名空间级）
• group：API 组（例如，apps、networking.k8s.io）
• version（必需）：API 版本（例如，v1、v1beta1）
• resource（必需）：资源名称（例如，deployments、services）
• namespace：命名空间（命名空间级资源必需）
• name（必需）：要发送请求的资源名称
• subresource：要发送请求的子资源（例如，exec）
• body（必需）：发送给资源的请求正文
• parameters：请求的可选参数

在 Pod 中执行命令的示例：

{
  "name": "post_resource",
  "arguments": {
    "resource_type": "namespaced",
    "group": "",
    "version": "v1",
    "resource": "pods",
    "namespace": "default",
    "name": "my-pod",
    "subresource": "exec",
    "body": {
      "command": ["ls", "-la", "/"],
      "container": "my-container",
      "timeout": 30
    }
  }
}

Pod exec 的 body 支持以下字段：

• command（必需）：要执行的命令，可以是字符串或字符串数组
• container（可选）：要在其中执行命令的容器名称（默认为第一个容器）
• timeout（可选）：超时时间，单位为秒（默认为 15 秒，最长为 60 秒）

关于超时的说明：

• 默认超时时间：未指定时为 15 秒
• 最长超时时间：60 秒（超过的值会被限制为此上限）
• 超过超时时间的命令将被终止，并返回超时错误

响应包含 stdout、stderr 和任何错误消息：

{
  "apiVersion": "v1",
  "kind": "Pod",
  "metadata": {
    "name": "my-pod",
    "namespace": "default"
  },
  "spec": {
    "command": ["ls", "-la", "/"]
  },
  "status": {
    "stdout": "total 48\ndrwxr-xr-x   1 root root 4096 May  5 14:30 .\ndrwxr-xr-x   1 root root 4096 May  5 14:30 ..\n...",
    "stderr": "",
    "error": ""
  }
}

MCP 资源

MKP 服务通过 MCP 资源提供对 Kubernetes 资源的访问。 资源 URI 遵循以下格式：

• 集群级资源：k8s://clustered/{group}/{version}/{resource}/{name}
• 命名空间级资源： k8s://namespaced/{namespace}/{group}/{version}/{resource}/{name}

配置

传输协议

MKP 支持 MCP 服务使用两种传输协议：

• Streamable HTTP：默认传输协议，适用于大多数使用场景
• SSE（Server-Sent Events）：旧版传输协议，主要用于兼容较早的客户端

你可以使用 CLI 标志或环境变量配置传输协议：

# Using CLI flag
./build/mkp-server --transport=sse

# Using environment variable
MCP_TRANSPORT=sse ./build/mkp-server

# Default (Streamable HTTP)
./build/mkp-server

在该环境中运行 MKP 时，ToolHive 会自动设置 MCP_TRANSPORT 环境变量。

控制资源发现

默认情况下，MKP 会将所有 Kubernetes 资源作为 MCP 资源提供，从而为大模型提供有用的上下文。不过，在资源众多的大型集群中，这可能会占用大量大模型上下文空间。

你可以使用 --serve-resources 标志禁用此行为：

# Run without serving cluster resources
./build/mkp-server --serve-resources=false

# Run with a specific kubeconfig without serving cluster resources
./build/mkp-server --kubeconfig=/path/to/kubeconfig --serve-resources=false

即使禁用了资源发现，MCP 工具（get_resource、list_resources、apply_resource、delete_resource 和 post_resource）仍可正常使用，让你能够与 Kubernetes 集群交互。

启用写入操作

默认情况下，MKP 以只读模式运行，这意味着不允许对集群执行写入操作，即 apply_resource、delete_resource 和 post_resource 工具将不可用。你可以使用 --read-write 标志启用写入操作：

# Run with write operations enabled
./build/mkp-server --read-write=true

# Run with a specific kubeconfig and write operations enabled
./build/mkp-server --kubeconfig=/path/to/kubeconfig --read-write=true

速率限制

MKP 内置了速率限制机制，用于保护服务免受过多 API 调用的影响，这在与 AI Agent 配合使用时尤为重要。速率限制器采用令牌桶算法，并根据操作类型应用不同的限制：

• 读取操作（list_resources、get_resource）：每分钟 120 个请求
• 写入操作（apply_resource、delete_resource）：每分钟 30 个请求
• 其他操作的默认限制：每分钟 60 个请求

速率限制按客户端会话应用，确保多个客户端之间公平分配资源。可以通过命令行标志启用或禁用速率限制功能：

# Run with rate limiting enabled (default)
./build/mkp-server

# Run with rate limiting disabled
./build/mkp-server --enable-rate-limiting=false

可以通过环境变量自定义速率限制：

• MKP_RATE_LIMIT_DEFAULT：默认速率限制（默认值：60）
• MKP_RATE_LIMIT_READ：读取操作速率限制（默认值：120）
• MKP_RATE_LIMIT_WRITE：写入操作速率限制（默认值：30）

# Run with custom rate limits
MKP_RATE_LIMIT_READ=200 MKP_RATE_LIMIT_WRITE=50 ./build/mkp-server

开发

运行测试

task test

格式化代码

task fmt

检查代码

task lint

更新依赖项

task deps

贡献

欢迎为此 MCP 服务贡献！如果您想参与贡献，请查看 贡献指南，了解如何开始。

如果您遇到错误或有功能请求，请在仓库中 提交问题，或加入我们的 社区 Discord 服务中的 #mcp-servers 频道。

许可证

本项目采用 Apache v2 许可证，详情请参阅 LICENSE 文件。