mcpField
K
Kubernetes Port Forward – Mcp Server

Kubernetes Port Forward – Mcp Server

本地服务
github.com/oijusti云与基础设施031 周前更新
代码仓库

关于 Kubernetes Port Forward – Mcp Server

为 MCP 客户端和 LLM 提供 Kubernetes 服务发现与 kubectl 端口转发工具，可通过调用启动单个或多个服务的转发，并可选择在独立终端窗口查看日志。

主要功能

  1. 01列出命名空间与服务
  2. 02按环境推断服务位置
  3. 03单次启动多个端口转发
  4. 04配置本地与远程端口
  5. 05可选独立窗口跟踪日志
  6. 06停止活动的转发进程

适用场景

  1. 01查找集群中的服务及其环境
  2. 02将多个服务映射到本地端口
  3. 03按指定命名空间启动转发
  4. 04停止由服务启动的端口转发

MCP 相关

该 MCP 服务向客户端暴露命名空间和服务查询、启动与停止端口转发的工具。转发通过 kubectl 执行，并可选择打开日志窗口。

#mcp#kubernetes#k8s#port-forward#terminal

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
  "mcpServers": {
    "k8s-port-forward": {
      "command": "npx",
      "args": [
        "-y",
        "k8s-port-forward-mcp"
      ]
    }
  }
}
启动命令npx -y k8s-port-forward-mcp

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包
npmk8s-port-forward-mcp0.0.8

工具

4

收录的工具列表 · 更新于 3 周前

参数类型必填说明
servicesarray是服务配置数组；每项可使用不同的 localPort、remotePort 和 namespace。

详细介绍

Kubernetes Port Forward MCP

一个 Model Context Protocol（MCP）服务，提供发现 Kubernetes 服务和运行 kubectl port-forward 会话的工具（可选择为每项服务打开单独的日志窗口）。它专为能够将自然语言转换为结构化工具调用的 MCP 客户端/大模型而设计。

Kubernetes Port Forward MCP 与 kubectl port-forward

此软件包在标准 kubectl 工作流之上提供 MCP 接口。

  • kubectl：适用于你已知确切的命名空间／Pod／端口，并且倾向于手动控制的情况。
  • MCP：适用于由 Agent 发现服务，并通过工具调用启动一个或多个端口转发的情况。

主要功能

  • 服务发现：列出命名空间，并根据运行中的 Pod 推断服务（短名称 → 环境 → 命名空间）。
  • 单个会话中转发多项服务：一次工具调用即可启动多个端口转发。
  • 适合大模型的 API：start_k8s_port_forward 接受一个数组，因此每项服务都可以使用不同的 namespace、environment、localPort 和 remotePort。
  • 可选日志：为每项服务在单独的操作系统终端窗口中打开 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"]
    }
  }
}

在 VS Code 中安装 在 VS Code Insiders 中安装

Amp

可通过 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

通过 Antigravity 设置添加，或更新你的配置文件：

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

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

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

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

Cline

按照配置 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

使用 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

使用 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
点击按钮进行安装：

在 Cursor 中安装

或手动安装：

前往 Cursor Settings -> MCP -> Add new MCP Server。名称可自行设定，选择 command 类型，并使用命令 npx -y k8s-port-forward-mcp@latest。你也可以点击 Edit 来验证配置或添加命令参数。

Factory

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

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

或者，在 Factory droid 中输入 /mcp，打开用于管理 MCP 服务的交互式界面。

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

Gemini CLI

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

Goose #### 点击按钮进行安装：

在 Goose 中安装

或手动安装：

前往 Advanced settings -> Extensions -> Add custom extension。名称可自行设置，类型选择 STDIO，并将 command 设置为 npx -y k8s-port-forward-mcp@latest。点击“Add Extension”。

Kiro

按照 MCP 服务文档操作。例如，在 .kiro/settings/mcp.json 中：

{
  "mcpServers": {
    "k8s-port-forward": {
      "command": "npx",
      "args": ["-y", "k8s-port-forward-mcp@latest"]
    }
  }
}
LM Studio
点击按钮进行安装：

将 MCP 服务 k8s-port-forward 添加到 LM Studio

或手动安装：

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

opencode

按照 MCP 服务文档操作。例如，在 ~/.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
    }
  }
}
Qodo Gen

在 VSCode 或 IntelliJ 中打开 Qodo Gen 聊天面板 -> Connect more tools -> + Add new MCP -> 粘贴上面的标准配置。

点击 Save。

VS Code
点击按钮进行安装：

在 VS Code 中安装 在 VS Code Insiders 中安装

或手动安装：

按照 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"]}'

安装后，即可在 VS Code 中将 Kubernetes Port Forward MCP 服务与 GitHub Copilot Agent 配合使用。

Warp

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

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

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

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

示例

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

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

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

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

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

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

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

详细工作流示例

用户：“在端口 3001 上运行 qa 环境中的 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（string，可选）：将结果筛选到某个命名空间。
    • 只读：true
端口转发

  • start_k8s_port_forward

    • 标题：启动端口转发
    • 描述：为一个或多个服务启动端口转发。
    • 参数：
      • services（array，必填）：服务配置列表。
        • serviceName（string，必填）：服务简称。（请先调用 list_k8s_services。）
        • localPort（number，必填）：要绑定的本地端口（1-65535）。
        • namespace（string，可选）：目标命名空间。
        • remotePort（number，可选）：远程（集群）端口。
        • environment（string，可选）：dev | qa | stg | prod。
        • includeLogs（boolean，可选）：是否在单独的窗口中打开日志（默认值：true）。
    • 只读：false

  • stop_k8s_port_forward

    • 标题：停止端口转发
    • 描述：停止此 MCP 服务启动的所有活动端口转发进程。
    • 参数：无
    • 只读：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>）。

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。