Kubernetes Port Forward MCP

一个模型上下文协议 (Model Context Protocol, MCP) 服务器，提供用于发现 Kubernetes 服务并运行 kubectl port-forward 会话（可选择使用单独的日志窗口）的工具。它专为将自然语言转换为结构化工具调用的 MCP 客户端/LLM 设计。

Kubernetes Port Forward MCP vs kubectl port-forward

该包在标准 kubectl 工作流之上提供了 MCP 接口。

• kubectl：当您已经知道确切的命名空间/ Pod /端口，并且更喜欢手动控制时最佳。

• MCP：当代理应通过工具调用发现服务并运行一个或多个端口转发时最佳。

Related MCP server: kubernetes-mcp-server

主要特性

• 服务发现：列出命名空间，并从正在运行的 Pod 中推断服务（短名称 → 环境 → 命名空间）。

• 单会话多服务：通过一次工具调用启动多个端口转发。

• LLM 友好的 API：start_k8s_port_forward 接受一个数组，因此每个服务可以使用不同的 namespace、environment、localPort 和 remotePort。

• 可选日志：为每个服务在单独的 OS 级终端窗口中打开 kubectl logs -f。

目录

• 要求

• 快速开始

• 开始使用

• 示例

• 工具

• 输出和日志

• 配置

• 验证和调试

要求

• Node.js 18 或更高版本

• 已安装 kubectl 并配置为可访问您的集群

• VS Code、Cursor、Windsurf、Claude Desktop、Cline 或任何其他 MCP 客户端

快速开始

1. 将此服务器添加到您的 MCP 客户端（使用下方“开始使用”中的配置）。

2. 向您的助手询问：“列出可用的 Kubernetes 服务。”

3. 向您的助手询问：“在本地端口 3002 上运行 api 服务。”

4. 打开返回的 URL（例如 http://localhost:3002）。

5. 完成后，询问：“停止所有端口转发。”

开始使用

首先，在您的客户端中安装 Kubernetes Port Forward MCP 服务器。

标准配置适用于大多数 MCP 客户端：

{
  "mcpServers": {
    "k8s-port-forward": {
      "command": "npx",
      "args": ["-y", "k8s-port-forward-mcp@latest"]
    }
  }
}

通过 Amp VS Code 扩展设置界面或更新您的 settings.json 文件来添加：

"amp.mcpServers": {
  "k8s-port-forward": {
    "command": "npx",
    "args": [
      "-y",
      "k8s-port-forward-mcp@latest"
    ]
  }
}

Amp CLI 设置：

通过下面的 amp mcp add 命令添加：

amp mcp add k8s-port-forward -- npx -y k8s-port-forward-mcp@latest

通过 Antigravity 设置或更新您的配置文件来添加：

{
  "mcpServers": {
    "k8s-port-forward": {
      "command": "npx",
      "args": ["-y", "k8s-port-forward-mcp@latest"]
    }
  }
}

使用 Claude Code CLI 添加 Kubernetes Port Forward MCP 服务器：

claude mcp add k8s-port-forward npx -y k8s-port-forward-mcp@latest

按照 MCP 安装指南，使用上面的标准配置。

按照 配置 MCP 服务器 一节的说明操作。

示例：本地设置

将以下内容添加到您的 cline_mcp_settings.json 文件中：

{
  "mcpServers": {
    "k8s-port-forward": {
      "type": "stdio",
      "command": "npx",
      "timeout": 30,
      "args": ["-y", "k8s-port-forward-mcp@latest"],
      "disabled": false
    }
  }
}

使用 Codex CLI 添加 Kubernetes Port Forward MCP 服务器：

codex mcp add k8s-port-forward npx "-y" "k8s-port-forward-mcp@latest"

或者，创建或编辑配置文件 ~/.codex/config.toml 并添加：

[mcp_servers.k8s-port-forward]
command = "npx"
args = ["-y", "k8s-port-forward-mcp@latest"]

有关更多信息，请参阅 Codex MCP 文档。

使用 Copilot CLI 以交互方式添加 Kubernetes Port Forward MCP 服务器：

/mcp add

或者，创建或编辑配置文件 ~/.copilot/mcp-config.json 并添加：

{
  "mcpServers": {
    "k8s-port-forward": {
      "type": "local",
      "command": "npx",
      "tools": ["*"],
      "args": ["-y", "k8s-port-forward-mcp@latest"]
    }
  }
}

有关更多信息，请参阅 Copilot CLI 文档。

点击按钮安装：

或手动安装：

转到 Cursor Settings -> MCP -> Add new MCP Server。按您的喜好命名，使用 command 类型，命令为 npx -y k8s-port-forward-mcp@latest。您还可以通过点击 Edit 验证配置或添加命令参数。

使用 Factory CLI 添加 Kubernetes Port Forward MCP 服务器：

droid mcp add k8s-port-forward "npx -y k8s-port-forward-mcp@latest"

或者，在 Factory droid 中键入 /mcp 以打开用于管理 MCP 服务器的交互式 UI。

有关更多信息，请参阅 Factory MCP 文档。

按照 MCP 安装指南，使用上面的标准配置。

点击按钮安装：

或手动安装：

转到 Advanced settings -> Extensions -> Add custom extension。按您的喜好命名，使用 STDIO 类型，并将 command 设置为 npx -y k8s-port-forward-mcp@latest。点击 “添加扩展”。

按照 MCP Servers 文档。例如在 .kiro/settings/mcp.json 中：

{
  "mcpServers": {
    "k8s-port-forward": {
      "command": "npx",
      "args": ["-y", "k8s-port-forward-mcp@latest"]
    }
  }
}

点击按钮安装：

或手动安装：

转到右侧边栏中的 Program -> Install -> Edit mcp.json。使用上面的标准配置。

按照 MCP Servers 文档。例如在 ~/.config/opencode/opencode.json 中：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "k8s-port-forward": {
      "type": "local",
      "command": ["npx", "-y", "k8s-port-forward-mcp@latest"],
      "enabled": true
    }
  }
}

在 VSCode 或 IntelliJ 中打开 Qodo Gen 聊天面板 -> 连接更多工具 -> + 添加新的 MCP -> 粘贴上面的标准配置。

点击 Save。

点击按钮安装：

或手动安装：

按照 MCP 安装指南，使用上面的标准配置。您还可以使用 VS Code CLI 安装 Kubernetes Port Forward MCP 服务器：

# For VS Code
code --add-mcp '{"name":"k8s-port-forward","command":"npx","args":["-y","k8s-port-forward-mcp@latest"]}'

安装后，Kubernetes Port Forward MCP 服务器将可在 VS Code 中与您的 GitHub Copilot 代理一起使用。

转到 Settings -> AI -> Manage MCP Servers -> + Add 以添加 MCP 服务器。使用上面的标准配置。

或者，在 Warp 提示符中使用斜杠命令 /add-mcp 并粘贴上面的标准配置：

{
  "mcpServers": {
    "k8s-port-forward": {
      "command": "npx",
      "args": [
        "-y",
        "k8s-port-forward-mcp@latest"
      ]
    }
  }
}

按照 Windsurf MCP 文档操作。使用上面的标准配置。

示例

快速参考（自然语言 → 工具调用）

• “在本地端口 3002、3003 上运行 api 和 auth 服务”
  → 先调用 list_k8s_services({})，然后调用 start_k8s_port_forward({ services: [{ serviceName: "api", localPort: 3002 }, { serviceName: "auth", localPort: 3003 }] })

• “从 shared-services 命名空间在本地端口 3000 运行 order 服务”
  → start_k8s_port_forward({ services: [{ serviceName: "order", namespace: "shared-services", localPort: 3000 }] })

• “从 shared-services 命名空间并在本地端口 3000 运行远程端口 3000 的 order 服务”
  → start_k8s_port_forward({ services: [{ serviceName: "order", namespace: "shared-services", localPort: 3000, remotePort: 3000 }] })

• “在 qa 环境中的本地端口 3001 上运行 api 服务”
  → start_k8s_port_forward({ services: [{ serviceName: "api", environment: "qa", localPort: 3001 }] })

• “从 production 命名空间在本地端口 3002 上运行 prod 环境中的 auth 服务”
  → start_k8s_port_forward({ services: [{ serviceName: "auth", environment: "prod", namespace: "production", localPort: 3002 }] })

• “停止所有端口转发”
  → stop_k8s_port_forward({})

详细工作流示例

用户：“在 qa 环境中的端口 3001 上运行 frontend 服务”

AI 工作流：

1. 调用 list_k8s_services({}) 查找确切的名称。

2. 收到包含例如 frontend: qa (ns: ...), dev (ns: ...) 的列表。

3. 调用 start_k8s_port_forward({ services: [{ serviceName: "frontend", environment: "qa", localPort: 3001 }] })。

4. 结果：端口转发在 MCP 服务器进程中运行；如果 includeLogs 为 true，日志将在单独的窗口中打开。工具结果包含 http://localhost:3001 和确切的 kubectl 命令。

工具

• list_k8s_namespaces

  • 标题：列出命名空间

  • 描述：列出所有可用的 Kubernetes 命名空间。

  • 参数：无

  • 只读：true

• list_k8s_services

  • 标题：列出服务

  • 描述：按短名称和环境分组的可用服务。

  • 参数：

    • namespace（字符串，可选）：将结果过滤到某个命名空间。

  • 只读：true

• start_k8s_port_forward

  • 标题：启动端口转发

  • 描述：为一个或多个服务启动端口转发。

  • 参数：

    • services（数组，必填）：服务配置列表。

      • serviceName（字符串，必填）：服务的短名称。（先调用 list_k8s_services。）

      • localPort（数字，必填）：要绑定的本地端口（1-65535）。

      • namespace（字符串，可选）：目标命名空间。

      • remotePort（数字，可选）：远程（集群）端口。

      • environment（字符串，可选）：dev | qa | stg | prod。

      • includeLogs（布尔值，可选）：是否在单独窗口中打开日志（默认值：true）。

  • 只读：false

验证与调试

由于 MCP 服务器会在后台启动实际的 kubectl 进程，您可能希望验证正在运行的内容并查看实际执行的命令。

检查正在运行的 kubectl 进程

Windows (PowerShell):

# List all kubectl processes
tasklist /fi "imagename eq kubectl.exe"

# See the exact commands with process IDs
Get-CimInstance Win32_Process -Filter "Name='kubectl.exe'" | Select-Object ProcessId,CommandLine

Linux/macOS:

# List all kubectl processes
ps aux | grep kubectl

# See the exact commands with process IDs
ps -ef | grep kubectl

这可以帮助您：

• 验证端口转发是否确实在运行

• 查看正在使用的确切命名空间和端口

• 识别可能需要手动终止的卡住进程

• 通过检查实际命令来调试连接问题

常见故障与修复

• 端口已被占用：选择另一个本地端口或停止冲突的进程。

• 连接被拒绝：验证服务名称、命名空间以及所选环境。

• 没有日志窗口：在端口转发请求中设置 includeLogs: true。

• 进程卡住：按 PID 终止（Windows 上使用 taskkill /PID <pid>，Linux/macOS 上使用 kill <pid>）。