MCP Kubernetes Ro

Kubernetes只读MCP服务器

](https://github.com/patrickdappollonio/mcp-kubernetes-ro/releases)

mcp-kubernetes-ro 是一个 模型上下文协议（MCP） 服务器为AI助手提供对Kubernetes集群的只读访问。它使人工智能模型能够列出资源，获取资源详细信息，检索pod日志，发现API资源，并执行base64编码/解码操作，同时通过只读访问保持安全。

服务器利用您的本地 kubectl 配置（即使在 kubectl 不需要安装），并为Kubernetes集群提供安全的只读接口，防止任何破坏性操作，同时允许全面的集群检查和故障排除功能。

特性

• 不需要 kubectl：MCP服务器使用您的本地 kubectl 配置以连接到Kubernetes集群，但不连接二进制文件，因此即使在以下情况下也能正常工作 kubectl 您的计算机上未安装。
• 资源列表：按类型列出任何Kubernetes资源，并可选择按标签、字段和命名空间进行筛选
• 资源详情：获取特定Kubernetes资源的完整详细信息
• Pod日志：使用高级过滤选项检索pod日志，包括grep模式、时间过滤和以前的日志
• 容器发现：列出Pod中用于目标日志访问的容器
• API发现：发现可用的Kubernetes API资源及其功能
• Base64实用程序：对Kubernetes机密和配置的base64数据进行编码和解码
• 多种运输方式：支持stdio和服务器发送事件（SSE）通信
• 只读安全：完全防止破坏性操作，同时保持全面的检查能力
• 资源访问控制：禁用对特定Kubernetes资源类型（例如Secrets）的访问，以防止AI代理查询敏感数据
• 命名空间支持：使用特定命名空间或集群范围的资源
• 高级过滤：支持标签选择器、字段选择器和分页
• 根据命令上下文：为单个命令指定不同的Kubernetes上下文
• 环境变量支持：KUBECONFIG环境变量的自动检测
• 端口转发（选择加入）：建立与pod端口的隧道连接以进行调试，支持每个会话多个端口
• 启动连接检查：启动时自动验证集群连接和基本权限

安装

请随时从 发布页面.

或者，您可以在macOS或Linux中使用Homebrew进行安装：

brew install patrickdappollonio/tap/mcp-kubernetes-ro

您也可以将其用作NPM包：只需确保将配置提供给您的AI代理：

npx -y @patrickdappollonio/mcp-kubernetes-ro

最后，Docker用户可以使用GitHub容器注册表中的预构建映像：

docker pull ghcr.io/patrickdappollonio/mcp-kubernetes-ro:latest

编辑器配置

将以下配置添加到编辑器的设置中以供使用 mcp-kubernetes-ro:

{
  "mcpServers": {
    "kubernetes-ro": {
      "command": "mcp-kubernetes-ro",
      "args": [
        // Uncomment and modify as needed:
        // "--kubeconfig=/path/to/kubeconfig",
        // "--namespace=default",
        // "--transport=stdio",
        // "--port=8080",
        // "--disabled-tools=get_logs,decode_base64",
        // "--disabled-resources=secrets",
        // "--always-start"
      ],
      "env": {
        // Set KUBECONFIG environment variable if needed:
        // "KUBECONFIG": "/path/to/kubeconfig",
        // Set MCP_KUBERNETES_RO_DISABLED_TOOLS environment variable if needed:
        // "MCP_KUBERNETES_RO_DISABLED_TOOLS": "get_logs,decode_base64",
        // Or use generic DISABLED_TOOLS environment variable:
        // "DISABLED_TOOLS": "get_logs,decode_base64",
        // Disable access to specific resource types:
        // "MCP_KUBERNETES_RO_DISABLED_RESOURCES": "secrets,configmaps",
        // Skip startup connectivity check via environment variable:
        // "MCP_KUBERNETES_RO_ALWAYS_START": "true"
      }
    }
  }
}

您可以使用 mcp-kubernetes-ro 直接从你的 $PATH 或者提供二进制文件的完整路径（例如。， /path/to/mcp-kubernetes-ro).

您还可以通过将其用作 npx 包裹：

{
  "mcpServers": {
    "kubernetes-ro": {
      "command": "npx",
      "args": [
        "-y",
        "@patrickdappollonio/mcp-kubernetes-ro"
        // Uncomment and modify as needed:
        // "--kubeconfig=/path/to/kubeconfig",
        // "--namespace=default",
        // "--transport=stdio",
        // "--port=8080",
        // "--disabled-tools=get_logs,decode_base64",
        // "--disabled-resources=secrets"
      ],
      "env": {
        // Set KUBECONFIG environment variable if needed:
        // "KUBECONFIG": "/path/to/kubeconfig",
        // Set MCP_KUBERNETES_RO_DISABLED_TOOLS environment variable if needed:
        // "MCP_KUBERNETES_RO_DISABLED_TOOLS": "get_logs,decode_base64",
        // Or use generic DISABLED_TOOLS environment variable:
        // "DISABLED_TOOLS": "get_logs,decode_base64",
        // Disable access to specific resource types:
        // "MCP_KUBERNETES_RO_DISABLED_RESOURCES": "secrets,configmaps"
      }
    }
  }
}

以下是如何利用Docker镜像：

{
  "mcpServers": {
    "kubernetes-ro": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "KUBECONFIG=/root/.kube/config",
        "-v", "/path/to/kubeconfig:/root/.kube/config",
        "ghcr.io/patrickdappollonio/mcp-kubernetes-ro"
        // Place additional flags here, like:
        // "--disabled-tools=get_logs,decode_base64",
        // "--disabled-resources=secrets"
      ],
      "env": {
        // Set KUBECONFIG environment variable if needed:
        // "KUBECONFIG": "/path/to/kubeconfig",
        // Set MCP_KUBERNETES_RO_DISABLED_TOOLS environment variable if needed:
        // "MCP_KUBERNETES_RO_DISABLED_TOOLS": "get_logs,decode_base64",
        // Or use generic DISABLED_TOOLS environment variable:
        // "DISABLED_TOOLS": "get_logs,decode_base64",
        // Disable access to specific resource types:
        // "MCP_KUBERNETES_RO_DISABLED_RESOURCES": "secrets,configmaps"
      }
    },
  }
}

请注意，您需要将kubeconfig文件挂载到容器中，然后设置 KUBECONFIG 将环境变量设置为挂载文件的路径，或使用 --kubeconfig 旗帜来设置它。

先决条件

• 有效的Kubernetes配置文件（通常 ~/.kube/config)
• 有效的凭据和集群访问权限（不需要kubectl二进制文件）
• 读取操作的适当RBAC权限
• 度量服务器 （度量工具所需）：用于度量功能(get_node_metrics, get_pod_metrics)，度量服务器必须安装在集群中。如果不可用，这些工具将返回错误消息。

可用的MCP工具

有 10工具 默认情况下可用，另外 3个附加工具 启用端口转发时：

• list_resources：按类型列出任何Kubernetes资源，可选过滤，最新排序在前。 metadata.managedFields 默认情况下省略，除非 include_managed_fields=true
• get_resource：获取具体的资源详细信息。 metadata.managedFields 默认情况下省略，除非 include_managed_fields=true
• get_logs：获取具有高级过滤选项的pod日志，包括grep模式、时间过滤和以前的日志
• get_pod_containers：列出pod中用于日志访问的容器
• list_api_resources：列出可用的Kubernetes API资源及其详细信息（类似于kubectl API-resources）
• list_contexts：从kubeconfig文件中列出可用的Kubernetes上下文
• get_node_metrics：获取节点指标（CPU和内存使用率）
• get_pod_metrics：获取pod指标（CPU和内存使用率）
• encode_base64：将文本数据编码为base64格式
• decode_base64：将base64数据解码为文本格式
• start_port_forward *（选择加入）*：使用一个或多个端口映射启动向pod的端口转发
• stop_port_forward *（选择加入）*：按ID停止活动端口转发会话
• list_port_forwards *（选择加入）*：列出所有活动端口转发会话

工具管理

禁用工具

您可以使用禁用特定工具 --disabled-tools 旗帜或 MCP_KUBERNETES_RO_DISABLED_TOOLS / DISABLED_TOOLS 环境变量。该标志是可重复的，接受逗号分隔的值：

# Comma-separated
mcp-kubernetes-ro --disabled-tools=get_logs,decode_base64

# Repeated flags
mcp-kubernetes-ro --disabled-tools=get_logs --disabled-tools=decode_base64

# Using environment variable
export MCP_KUBERNETES_RO_DISABLED_TOOLS=get_logs,decode_base64
mcp-kubernetes-ro

来自标志和环境变量的值被合并。如果 MCP_KUBERNETES_RO_DISABLED_TOOLS env-var未设置， DISABLED_TOOLS 被用作后备方案。

当工具被禁用时，它将不会在MCP服务器上注册，也不会出现在可用工具列表中。stderr将记录一条消息，指示跳过了哪些工具。

可用于禁用的工具名称：

• list_resources
• get_resource
• get_logs
• get_pod_containers
• list_api_resources
• list_contexts
• get_node_metrics
• get_pod_metrics
• encode_base64
• decode_base64
• start_port_forward *（仅当启用端口转发时）*
• stop_port_forward *（仅当启用端口转发时）*
• list_port_forwards *（仅当启用端口转发时）*

禁用对特定资源的访问

您可以使用以下命令阻止AI代理查询特定的Kubernetes资源类型 --disabled-resources 旗帜或 MCP_KUBERNETES_RO_DISABLED_RESOURCES 环境变量。这对于防止访问机密等敏感资源特别有用。

资源可以按名称（单数、复数、种类或简称）或完整名称指定 group/version/resource 三倍的。这 core 关键字用作Kubernetes核心API组的别名。所有名称都在启动时根据集群的发现API进行解析，因此单数名称、种类名称和短名称都被接受：

# By resource name (resolved via the cluster's discovery API)
mcp-kubernetes-ro --disabled-resources=secrets

# Singular, kind, and short names all work
mcp-kubernetes-ro --disabled-resources=secret      # singular
mcp-kubernetes-ro --disabled-resources=Secret      # kind
mcp-kubernetes-ro --disabled-resources=cm          # short name for configmaps

# Full group/version/resource format
mcp-kubernetes-ro --disabled-resources=core/v1/secrets

# Multiple resources (comma-separated or repeated flags)
mcp-kubernetes-ro --disabled-resources=secrets,configmaps
mcp-kubernetes-ro --disabled-resources=secrets --disabled-resources=configmaps

# Non-core API groups
mcp-kubernetes-ro --disabled-resources=apps/v1/deployments

# Using environment variable
export MCP_KUBERNETES_RO_DISABLED_RESOURCES=secrets,configmaps
mcp-kubernetes-ro

当通过查询禁用资源时 list_resources 或 get_resource，服务器返回一个明确的错误：

access to resource "secrets" (core/v1/secrets) is disabled by configuration and cannot be queried

禁用资源也隐藏起来 list_api_resources 输出，因此AI代理不会发现它们是可用的。

如果无法针对集群解析资源名称（例如，拼写错误或不存在的CRD），服务器将拒绝以描述性错误开始——确保禁用的资源始终生效。

运行模式

标准（stdio）模式

默认情况下， mcp-kubernetes-ro 在stdio模式下运行，该模式适合与编辑器和其他通过标准输入/输出进行通信的工具集成。

mcp-kubernetes-ro

服务器发送事件（SSE）模式

或者，您可以跑步 mcp-kubernetes-ro 作为支持SSE的HTTP服务器，用于基于web的集成：

mcp-kubernetes-ro --transport=sse --port=8080

在SSE模式下，服务器将侦听指定的端口（默认值：8080），并使用服务器发送事件通过HTTP提供相同的MCP工具。这对于不能进行stdio通信的web应用程序或环境非常有用。

配置选项

以下命令行标志可用于配置MCP服务器：

Kubernetes配置

• --kubeconfig=PATH：kubeconfig文件的路径（默认为 KUBECONFIG 环境变量，然后 ~/.kube/config)
• --namespace=NAME：操作的默认命名空间（默认为当前命名空间）

运输选项

• --transport=TYPE：运输类型： stdio 或 sse （默认值： stdio)
• --port=PORT：SSE服务器的端口（默认值：8080，仅与 --transport=sse)

工具和资源管理

• --disabled-tools=NAMES：要禁用、可重复和逗号分隔的工具名称（可选）
• --disabled-resources=RESOURCES：要阻止的资源类型，可重复和逗号分隔（可选）。接受资源名称(secrets, deploy, cm)或完整规格(core/v1/secrets, apps/v1/deployments)
• MCP_KUBERNETES_RO_DISABLED_TOOLS：禁用工具的环境变量（与标志值合并，回退： DISABLED_TOOLS)
• MCP_KUBERNETES_RO_DISABLED_RESOURCES：禁用资源的环境变量（与标志值合并）

端口转发

• --enable-port-forwarding：启用端口转发工具（默认禁用）
• MCP_KUBERNETES_RO_ENABLE_PORT_FORWARDING：应用程序特定的环境变量（设置为 true, 1，或 yes)
• ENABLE_PORT_FORWARDING：通用环境变量（设置为 true, 1，或 yes)

上下文配置

服务器支持每个命令上下文。这为在同一个Kubernetes集群或上下文中使用多个Kubernetes集群提供了更大的灵活性 $KUBECONFIG 文件。

配置优先级：

1. 命令级上下文：使用 context 单个工具调用中的参数
2. Kubeconfig默认值：使用kubeconfig文件中指定的当前上下文

Kubeconfig分辨率优先级：

1. 命令行标志: --kubeconfig 参数
2. 环境变量: KUBECONFIG 环境变量
3. 默认路径: ~/.kube/config
4. 在集群配置中：在Kubernetes pod内运行时自动检测

示例：

{
  "resource_type": "pods",
  "namespace": "default",
  "context": "production-cluster"
}

这种方法允许您：

• 在同一会话中为不同的操作使用不同的上下文
• 在不重新启动服务器的情况下按命令切换上下文
• 保持与现有kubeconfig设置的兼容性

工具使用文档

列出资源

按类型列出任何Kubernetes资源，并可选择过滤，按最新者排序。

论据：

• resource_type （必填）：要列出的资源类型-使用复数形式（例如，“pod”、“deployments”、“services”）
• api_version （可选）：资源的API版本（例如，“v1”、“apps/v1”）
• namespace （可选）：目标命名空间（为集群范围的资源留空）
• context （可选）：要使用的Kubernetes上下文（默认为kubeconfig中的当前上下文）
• label_selector （可选）：用于过滤资源的标签选择器（例如，“app=nginx，version=1.0”）
• field_selector （可选）：用于筛选资源的字段选择器（例如，“status.phase=Running”）
• limit （可选）：要返回的最大资源数（默认为全部）
• continue （可选）：继续标记分页（来自之前的响应）

例子：

{
  "resource_type": "pods",
  "namespace": "default",
  "context": "production",
  "label_selector": "app=nginx"
}

获取资源

获取具有完整配置的特定资源详细信息。

论据：

• resource_type （必填）：要获取的资源类型
• name （必填）：资源名称
• api_version （可选）：资源的API版本（例如，“v1”、“apps/v1”）
• namespace （可选）：目标命名空间（命名空间资源需要）
• context （可选）：要使用的Kubernetes上下文（默认为kubeconfig中的当前上下文）

例子：

{
  "resource_type": "deployment",
  "name": "nginx-deployment",
  "namespace": "default",
  "context": "production"
}

获取日志

获取具有高级过滤选项的pod日志，包括grep模式、时间过滤和以前的日志。

论据：

• namespace （必需）：Pod命名空间
• name （必填）：Pod名称
• container （可选）：容器名称（多容器Pod需要）
• context （可选）：要使用的Kubernetes上下文（默认为kubeconfig中的当前上下文）
• max_lines （可选）：要检索的最大行数
• grep_include （可选）：仅包含与这些模式匹配的行（逗号分隔）。工作方式类似于grep，包括包含以下任何模式的行
• grep_exclude （可选）：排除与这些模式匹配的行（逗号分隔）。类似grep-v的工作方式-排除包含任何这些模式的行
• use_regex （可选）：是否将grep模式视为正则表达式而不是文字字符串
• since （可选）：返回比此时间更新的日志。支持“5m”、“1h”、“2h30m”、“1d”等持续时间或“2023-01-01T10:00:00Z”等绝对时间
• previous （可选）：返回上一个终止的容器实例的日志（如kubectl logs--previous）

例子：

{
  "namespace": "default",
  "name": "nginx-pod-12345",
  "container": "nginx",
  "context": "production",
  "max_lines": "100",
  "grep_include": "error,warning",
  "since": "5m"
}

获取Pod容器

列出pod中用于日志访问的容器。

论据：

• namespace （必需）：Pod命名空间
• name （必填）：Pod名称
• context （可选）：要使用的Kubernetes上下文（默认为kubeconfig中的当前上下文）

例子：

{
  "namespace": "default",
  "name": "nginx-pod-12345",
  "context": "production"
}

列出API资源

列出可用的Kubernetes API资源及其详细信息（类似于kubectl API-resources）。

论据：

• 无需

例子：

{}

列出上下文

从kubeconfig文件中列出可用的Kubernetes上下文。这对于发现哪些上下文可用于 context 其他工具中的参数。

论据：

• 无需

例子：

{}

示例响应：

{
  "contexts": [
    {
      "name": "production",
      "cluster": "prod-cluster",
      "user": "prod-user",
      "namespace": "default",
      "current": true
    },
    {
      "name": "staging",
      "cluster": "staging-cluster",
      "user": "staging-user",
      "namespace": "staging",
      "current": false
    }
  ],
  "count": 2
}

获取节点指标

从指标服务器获取节点指标（CPU和内存使用情况）。由于内置的度量服务器端点不支持基于指针的分页，因此结果按时间戳（最新的优先）排序，以实现一致的排序和分页。

论据：

• node_name （可选）：获取指标的特定节点名称。如果未提供，则返回所有节点的指标。
• context （可选）：要使用的Kubernetes上下文（默认为kubeconfig中的当前上下文）
• limit （可选）：要返回的最大节点度量数。如果未提供，则返回所有可用指标。
• continue （可选）：继续标记分页（来自之前的响应）。

错误处理：

• 如果度量服务器不可用，则返回错误消息
• 检测常见指标服务器错误并提供具体指导

例子：

{
  "node_name": "worker-node-1",
  "context": "production",
  "limit": 5
}

示例响应（单节点）：

{
  "kind": "NodeMetrics",
  "apiVersion": "metrics.k8s.io/v1beta1",
  "metadata": {
    "name": "worker-node-1",
    "creationTimestamp": "2023-01-01T12:00:00Z"
  },
  "timestamp": "2023-01-01T12:00:00Z",
  "window": "10.062s",
  "usage": {
    "cpu": "137m",
    "memory": "1368128Ki"
  }
}

示例响应（带分页的列表）：

{
  "kind": "NodeMetricsList",
  "apiVersion": "metrics.k8s.io/v1beta1",
  "count": 5,
  "items": [
    {
      "kind": "NodeMetrics",
      "metadata": { "name": "node-1" },
      "timestamp": "2023-01-01T12:00:00Z",
      "usage": { "cpu": "137m", "memory": "1368128Ki" }
    }
  ],
  "continue": "eyJvZmZzZXQiOjUsInR5cGUiOiJub2RlIiwibmFtZXNwYWNlIjoiIn0="
}

获取Pod指标

从指标服务器获取pod指标（CPU和内存使用情况）。由于内置的度量服务器端点不支持基于指针的分页，因此结果按时间戳（最新的优先）排序，以实现一致的排序和分页。

论据：

• namespace （可选）：从中获取pod度量的命名空间。如果没有提供，则返回所有命名空间中所有Pod的度量。
• pod_name （可选）：获取指标的特定pod名称。需要 namespace 如果指定。
• context （可选）：要使用的Kubernetes上下文（默认为kubeconfig中的当前上下文）
• limit （可选）：要返回的pod指标的最大数量。如果未提供，则返回所有可用指标。
• continue （可选）：继续标记分页（来自之前的响应）。

错误处理：

• 如果度量服务器不可用，则返回错误消息
• 检测常见指标服务器错误并提供具体指导
• 验证 namespace 在以下情况下提供 pod_name 被指定

分页说明：

• 继续令牌具有上下文感知功能，如果命名空间上下文发生变化，则会重置
• 客户端分页实现了一致的排序和过滤

示例（特定Pod）：

{
  "namespace": "kube-system",
  "pod_name": "metrics-server-557ff575fb-9dcl4",
  "context": "production"
}

示例（带分页）：

{
  "namespace": "kube-system",
  "context": "production",
  "limit": 10,
  "continue": "eyJvZmZzZXQiOjEwLCJ0eXBlIjoicG9kIiwibmFtZXNwYWNlIjoia3ViZS1zeXN0ZW0ifQ=="
}

示例响应（单Pod）：

{
  "kind": "PodMetrics",
  "apiVersion": "metrics.k8s.io/v1beta1",
  "metadata": {
    "name": "metrics-server-557ff575fb-9dcl4",
    "namespace": "kube-system",
    "creationTimestamp": "2023-01-01T12:00:00Z"
  },
  "timestamp": "2023-01-01T12:00:00Z",
  "window": "18.888s",
  "containers": [
    {
      "name": "metrics-server",
      "usage": {
        "cpu": "8020419n",
        "memory": "48164Ki"
      }
    }
  ]
}

示例响应（带分页的列表）：

{
  "kind": "PodMetricsList",
  "apiVersion": "metrics.k8s.io/v1beta1",
  "namespace": "kube-system",
  "count": 10,
  "items": [
    {
      "kind": "PodMetrics",
      "metadata": { "name": "pod-1", "namespace": "kube-system" },
      "timestamp": "2023-01-01T12:00:00Z",
      "containers": [
        {
          "name": "container-1",
          "usage": { "cpu": "8020419n", "memory": "48164Ki" }
        }
      ]
    }
  ],
  "continue": "eyJvZmZzZXQiOjIwLCJ0eXBlIjoicG9kIiwibmFtZXNwYWNlIjoia3ViZS1zeXN0ZW0ifQ=="
}

编码Base64

将文本数据编码为base64格式。

论据：

• data （必填）：要编码的文本数据

例子：

{
  "data": "username:password"
}

解码Base64

将base64数据解码为文本格式。

论据：

• data （必需）：要解码的Base64数据

例子：

{
  "data": "dXNlcm5hbWU6cGFzc3dvcmQ="
}

端口转发（选择加入）

端口转发是 默认情况下禁用 因为它超越了只读操作。虽然它不会修改任何集群状态（不会创建、更新或删除任何资源），但它会建立从本地计算机到pod端口的活动网络隧道。这意味着流量可以流过这些隧道，这些隧道可以与正在运行的应用程序交互，例如，到达HTTP端点、连接到数据库或在目标服务中触发副作用。因此，必须明确启用端口转发。

使用启用它 --enable-port-forwarding 标志或通过设置 MCP_KUBERNETES_RO_ENABLE_PORT_FORWARDING 环境变量 true.

\[！警告\] 端口转发可以定位 任何吊舱 在kubeconfig凭据可以访问的集群中，包括基础设施Pod。如果Kubernetes API服务器本身作为pod运行（例如，在自托管或某些托管设置中），理论上AI代理可以转发到它 不授予其他特权 -您仍然需要有效的凭据和RBAC权限才能对API服务器进行身份验证-如果其他本地工具或脚本发现API服务器，则在本地端口上公开该服务器可能会导致意外的交互。请始终查看您的RBAC策略，并考虑使用 --disabled-resources 以及端口转发，以限制AI代理可以发现和瞄准的内容。

\[！警告\] 跑步时 SSE模式 (--transport=sse)在远程服务器上，转发的端口绑定到 服务器的本地接口，而不是你的工作站。这意味着 localhost: 指机器 mcp-kubernetes-ro 正在运行。要从工作站访问转发的服务，您必须公开这些端口，例如通过SSH隧道(ssh -L :localhost: user@remote-host)或其他网络配置。在stdio模式下，这不是问题，因为服务器与编辑器一起在本地运行。

启用后，将提供三个附加工具：

启动端口转发

建立到Kubernetes pod的端口转发会话。支持在单个会话中转发多个端口。每个端口映射都将本地端口转发到pod上的端口。集 local_port 到 0 （或省略它）让系统自动分配一个空闲的本地端口。

论据：

• namespace （必需）：Pod命名空间
• pod （必填）：Pod名称
• ports （必填）：端口映射数组，每个映射都有：

- pod_port （必填）：吊舱上要转发的端口（1-65535） - local_port （可选）：要侦听的本地端口（0或省略以自动分配）

• context （可选）：要使用的Kubernetes上下文（默认为kubeconfig中的当前上下文）

示例（单端口，自动分配）：

{
  "namespace": "default",
  "pod": "my-app-pod-abc123",
  "ports": [
    { "pod_port": 8080 }
  ]
}

示例（多个端口，显式本地端口）：

{
  "namespace": "default",
  "pod": "my-app-pod-abc123",
  "ports": [
    { "pod_port": 8080, "local_port": 18080 },
    { "pod_port": 5432, "local_port": 15432 }
  ]
}

示例响应：

{
  "id": "pf-1",
  "namespace": "default",
  "pod": "my-app-pod-abc123",
  "ports": [
    { "pod_port": 8080, "local_port": 18080 },
    { "pod_port": 5432, "local_port": 15432 }
  ],
  "started_at": "2025-01-15T10:30:00Z"
}

停止端口前进

通过ID终止活动端口转发会话。

论据：

• id （必填）：端口转发会话ID（例如。， "pf-1")

例子：

{
  "id": "pf-1"
}

示例响应：

{
  "id": "pf-1",
  "stopped": true
}

列出端口转发

列出所有活动端口转发会话及其端口映射和元数据。不争论。

例子：

{}

示例响应：

{
  "count": 2,
  "port_forwards": [
    {
      "id": "pf-1",
      "namespace": "default",
      "pod": "my-app-pod-abc123",
      "ports": [
        { "pod_port": 8080, "local_port": 18080 }
      ],
      "started_at": "2025-01-15T10:30:00Z"
    },
    {
      "id": "pf-2",
      "namespace": "monitoring",
      "pod": "grafana-xyz789",
      "ports": [
        { "pod_port": 3000, "local_port": 13000 }
      ],
      "started_at": "2025-01-15T10:35:00Z"
    }
  ]
}

端口转发行为

• 自动清理：如果目标pod被删除或连接中断，端口转发会话将自动删除。后续电话 list_port_forwards 将不再显示已终止的会话。
• 优雅关闭：当MCP服务器停止时（通过 SIGINT 或 SIGTERM)，终止所有活动端口转发会话。
• 会话ID：每个会话获得一个唯一的递增ID（例如。， pf-1, pf-2).使用此ID stop_port_forward 以终止特定会话。
• 多个会话：您可以同时激活多个端口转发会话，每个会话都针对不同的Pod或端口。

带端口转发的编辑器配置

{
  "mcpServers": {
    "kubernetes-ro": {
      "command": "mcp-kubernetes-ro",
      "args": [
        "--enable-port-forwarding"
      ],
      "env": {
        // Or use the environment variable instead of the flag:
        // "MCP_KUBERNETES_RO_ENABLE_PORT_FORWARDING": "true"
      }
    }
  }
}

示例

基本使用示例

# Start with default kubeconfig and context
mcp-kubernetes-ro

# Start with specific kubeconfig
mcp-kubernetes-ro --kubeconfig ~/.kube/config

# Start with KUBECONFIG environment variable
export KUBECONFIG=~/.kube/config
mcp-kubernetes-ro

# Start with specific namespace
mcp-kubernetes-ro --namespace kube-system

# Start in SSE mode
mcp-kubernetes-ro --transport=sse --port=3000

# Start with port forwarding enabled
mcp-kubernetes-ro --enable-port-forwarding

# Start with port forwarding via environment variable
export MCP_KUBERNETES_RO_ENABLE_PORT_FORWARDING=true
mcp-kubernetes-ro

高级配置示例

# Production cluster with specific kubeconfig
mcp-kubernetes-ro \
  --kubeconfig ~/.kube/prod-config \
  --namespace monitoring

# Development setup with SSE mode using environment variable
export KUBECONFIG=~/.kube/dev-config
mcp-kubernetes-ro \
  --transport=sse \
  --port=8080

# Using per-command context (specify context in tool calls)
# Context is now specified at the tool level, not globally

# Disable specific tools for security or performance reasons
mcp-kubernetes-ro --disabled-tools=get_logs,decode_base64

# Disable metrics tools when metrics server is not available
mcp-kubernetes-ro --disabled-tools=get_node_metrics,get_pod_metrics

# Prevent AI agents from reading Secrets and ConfigMaps
mcp-kubernetes-ro --disabled-resources=secrets --disabled-resources=configmaps

# Lock down a production environment: no logs, no secrets, no base64 decoding
mcp-kubernetes-ro \
  --kubeconfig ~/.kube/prod-config \
  --disabled-tools=get_logs,decode_base64 \
  --disabled-resources=secrets

# Use environment variables for disabled tools and resources
export MCP_KUBERNETES_RO_DISABLED_TOOLS=get_logs,decode_base64
export MCP_KUBERNETES_RO_DISABLED_RESOURCES=secrets
mcp-kubernetes-ro

用例

群集故障排除

• 跨命名空间列出失败的Pod
• 获取详细的资源配置
• 检索pod日志以进行调试
• 发现可用的API资源

资源发现

• 按类型探索集群资源
• 查找具有特定标签的资源
• 了解资源关系
• 确定资源配置

安全与合规

• 只读访问可防止意外更改
• 检查配置，无修改风险
• 审核资源状态和设置
• 生产集群安全探索

人工智能辅助操作

• 让AI助手帮助诊断集群问题
• 获取资源问题的智能建议
• 自动日志分析和模式识别
• Kubernetes资源的自然语言查询

AI助手注意事项

虽然此MCP服务器为Kubernetes集群检查提供了全面的工具，但一些AI助手可能存在限制或策略，即使在技术上可用的情况下，也无法使用某些工具组合：

潜在限制

• 秘密访问：一些AI助手可能会拒绝检索、解码或显示Kubernetes机密（甚至使用提供的 get_resource 和 decode_base64 由于围绕凭据处理的安全策略
• 敏感数据：无论用户权限或工具可用性如何，人工智能模型都可能对在聊天界面中暴露敏感信息有内置限制
• 安全模式：某些人工智能助理将安全最佳实践置于技术能力之上，可能会拒绝可能暴露敏感数据的操作

变通方法

如果您的AI助手出于安全原因拒绝使用可用工具：

1. 直接CLI访问：使用 kubectl 直接用于敏感操作，只需让AI给你运行命令，例如：

   kubectl get secret  -n  -o yaml
   echo "" | base64 -d

1. 手动工具使用：如果以编程方式使用MCP服务器，请直接调用工具，而不是通过AI助手

1. 文档：考虑安全影响——人工智能的拒绝实际上可能是为了保护您免受无意中的凭证暴露

设计理念

这种行为反映了不同的安全方法：

• 基于工具：如果你有工具和权限，你应该能够使用它们
• AI安全：将防止意外暴露置于技术能力之上

这两种观点都是有效的，在设计涉及敏感数据检索的工作流时，应该考虑这一限制。

启动连接检查

MCP服务器在启动时执行自动连接检查，以验证它是否可以成功连接到Kubernetes集群。此检查包括：

1. API服务器可达性：验证Kubernetes API服务器是否可访问并响应
2. 认证：确认您的凭据有效并被群集接受
3. API发现：服务器可以发现可用API资源的测试
4. 基本许可：验证您是否至少具有命名空间的读取权限（基本RBAC检查）

你会看到什么

成功启动后，您将看到如下输出：

Testing connectivity to Kubernetes cluster...
✓ Successfully connected to Kubernetes cluster (version: v1.28.0)

解决连接问题

如果连接检查失败，您将看到一条详细的错误消息。常见问题包括：

• kubeconfig无效：检查kubeconfig文件是否存在并且格式正确
• 无法访问群集：验证是否可以从网络访问群集终结点
• 认证失败：确保您的凭据未过期且有效
• 权限不足：验证您至少具有基本群集资源的读取权限

连接检查有10秒的超时时间，以防止挂在无响应的集群上。

跳过连接检查(--always-start)

如果您的凭据是通过OIDC浏览器流或其他机制授予的，而MCP服务器进程启动时令牌尚未生效，请使用 --always-start 旗帜（或 MCP_KUBERNETES_RO_ALWAYS_START=true 环境变量）完全跳过启动连接检查：

mcp-kubernetes-ro --always-start

随着 --always-start，服务器立即启动，不与集群联系。连接检查实际上被推迟了：第一次调用工具时，它将尝试正常访问集群。如果集群无法访问或凭据已过期，该工具将向AI返回一条结构化错误消息，指示其不要自动重试，并提示您重新进行身份验证。

通过配置资源筛选器 --disabled-resources 同样被推迟：名称解析发生在第一次工具调用时，而不是在启动时，因此启动服务器不需要集群连接。

安全注意事项

• 只读访问：服务器仅支持读取操作(get, list, watch)
• 资源访问控制：阻止AI代理使用以下命令查询特定资源类型（例如Secrets） --disabled-resources
• 本地身份验证：使用您现有的kubectl配置和凭据
• 无破坏性操作：无法创建、更新或删除资源
• 命名空间隔离：尊重kubeconfig中的RBAC权限
• 安全通信：支持基于stdio和HTTPS的SSE通信

指标实施细节

错误检测和处理

度量工具(get_node_metrics 和 get_pod_metrics)包括用于度量服务器可用性的复杂错误检测：

• 自动检测：检测指标服务器何时未安装或没有响应
• 有用的错误消息：在缺少度量服务器时提供特定的安装命令
• 常见错误模式：识别各种指标服务器错误情况：

- metrics-server 未找到服务 - metrics.k8s.io API组不可用 - “服务器找不到请求的资源”错误 - “无可用指标”条件

分页实现

这两种度量工具都实现了客户端分页以获得一致的结果，因为内置的度量服务器端点不支持基于指针的分页，并且还为人工智能工具提供了一种安全的方式来请求所需的数据，这在小型上下文窗口中特别有用。

• 排序：在分页之前，所有结果都按时间戳（最新的第一个）排序
• 继续代币：Base64编码的JSON令牌包含：

- offset：结果集中的当前位置 - type：资源类型（“节点”或“pod”） - namespace：上下文命名空间（用于pod度量）

• 情境感知：命名空间上下文更改时分页状态重置
• 令牌格式: eyJvZmZzZXQiOjEwLCJ0eXBlIjoicG9kIiwibmFtZXNwYWNlIjoia3ViZS1zeXN0ZW0ifQ==

资源检索策略

• 提取然后过滤：始终从服务器检索所有可用指标，然后应用客户端过滤和分页
• 一致的订购：确保分页请求的结果可预测
• 命名空间范围界定：在提供时自动将pod指标范围限定到特定命名空间

错误处理

服务器为常见问题提供详细的错误消息：

• 无效的资源类型或API版本
• 缺少必要参数
• RBAC权限错误
• 网络连接问题
• kubeconfig文件格式错误
• 度量服务器不可用性（附安装指南）

局限性

• 需要本地kubectl配置
• 只读访问（无写操作）
• 仅限于您的kubeconfig凭据可访问的资源
• 无实时日志流（仅静态检索）
• 不支持API资源之外的自定义资源定义发现