Kubernetes Port Forward MCP
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 客户端
快速开始
将此服务器添加到您的 MCP 客户端(使用下方“开始使用”中的配置)。
向您的助手询问:“列出可用的 Kubernetes 服务。”
向您的助手询问:“在本地端口 3002 上运行 api 服务。”
打开返回的 URL(例如
http://localhost:3002)。完成后,询问:“停止所有端口转发。”
开始使用
首先,在您的客户端中安装 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 工作流:
调用
list_k8s_services({})查找确切的名称。收到包含例如
frontend: qa (ns: ...), dev (ns: ...)的列表。调用
start_k8s_port_forward({ services: [{ serviceName: "frontend", environment: "qa", localPort: 3001 }] })。结果:端口转发在 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,CommandLineLinux/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>)。
Available Tools
4 toolslist_k8s_namespacesA
List all available Kubernetes namespaces.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It tells the tool is read-only ('List'), which is good. However, it does not disclose other behavioral traits such as pagination, ordering, authentication needs, or whether it returns errors for RBAC issues. It is adequate but lacks completeness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one sentence of eight words. Every word is meaningful: 'List' for action, 'all available' for scope, 'Kubernetes namespaces' for resource. No wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless tool with no output schema, the description is succinct and covers the purpose and scope. It explains what the user will get (list of namespaces). It could be improved by mentioning if the list is filtered by the current kubeconfig context or if it includes all clusters, but given the simplicity, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema description coverage is 100%, so the schema already defines the tool fully. The description adds value by confirming that no parameters are needed and that the output will contain all namespaces. Nothing more is needed from the description on parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List'), the resource ('all available Kubernetes namespaces'), and differentiates from siblings like list_k8s_services which list services. It specifies scope ('all available') and resource type ('namespaces'), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you need to see which namespaces exist in a cluster. However, it provides no guidance on when not to use it (e.g., if only specific namespaces are needed) and does not mention alternatives among siblings. It does not explain prerequisites or context like cluster access requirements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_k8s_servicesA
Retrieves a list of all available Kubernetes services grouped by short name and environment. Use this to find exact service names and namespaces before calling start_k8s_port_forward.
| Name | Required | Description | Default |
|---|---|---|---|
| namespace | No | Optional: Filter by namespace |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations are provided, the description clearly indicates that this is a read-only operation (retrieving lists), which is the core behavioral trait. It does not explicitly state that it is non-destructive, but the language strongly implies it, and there are no contradictions. A minor point is the lack of mention about performance or rate limits, but the simplicity of the tool makes this less critical.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at two sentences, each providing distinct and valuable information: the first explains what it does, the second explains when to use it. It is front-loaded with the primary purpose. It could be slightly more polished by omitting 'all available' as implied, but it remains efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (1 optional param, no output schema, no annotations), the description is sufficient for an agent to understand its purpose and how to use it in relation to siblings. It lacks explicit details about the return format, but the simplicity of the tool and the context that it returns 'grouped' lists mitigates this. For a read-only list tool, this is complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, meaning the schema itself documents the optional namespace filter. The description goes beyond the schema by stating it groups results by 'short name and environment', which adds useful semantic context about how the returned list is structured, aiding the agent in understanding what to expect.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Retrieves' and clearly identifies the resource as 'Kubernetes services grouped by short name and environment'. This clearly distinguishes the tool from siblings like list_k8s_namespaces, which lists namespaces, not services.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states to use this tool before calling start_k8s_port_forward, providing a clear when-to-use and linkage to an alternative (the sibling tool). It also implies its role as a prerequisite, offering high-quality guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
start_k8s_port_forwardA
Starts port forwarding for one or more Kubernetes services. Call list_k8s_services (and optionally list_k8s_namespaces) first to resolve exact service names and namespaces. All port-forwards run in a single session; logs open in separate OS windows when includeLogs is true.
| Name | Required | Description | Default |
|---|---|---|---|
| services | Yes | Array of service configs; each can use different localPort, remotePort, namespace. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool starts a process (mutation), that multiple forwards share a session, and that logs open in separate windows if includeLogs is true. However, it does not describe blocking behavior, failure modes, resource limits, or what the tool returns (no output schema exists). These gaps limit transparency for a potentially long-running operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no wasted words. The main action is in the first sentence, followed by usage guidance and behavioral notes. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the prerequisite steps and session behavior, but it omits key details for a tool with no output schema: return value, success/failure signaling, and how to stop the port forwarding (though a sibling tool exists). For a tool that initiates a persistent process, additional context about lifecycle and results would be needed for full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters are described in the input schema (100% coverage), so the description is not required to add much. The description reinforces that service names and namespaces should be resolved beforehand and that each service config can differ, but it does not add new meaning beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear verb 'Starts' and resource 'port forwarding for one or more Kubernetes services'. It distinguishes from sibling tools like list_k8s_services (listing) and stop_k8s_port_forward (stopping), making the tool's core purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises calling list_k8s_services and optionally list_k8s_namespaces first to resolve exact names, establishing a clear prerequisite workflow. It also notes that all port-forwards run in a single session, implying session management context. However, it does not specify when *not* to use this tool or mention alternatives like stop_k8s_port_forward for a different phase.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
stop_k8s_port_forwardA
Stop all active Kubernetes port-forward processes.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states 'stop all active,' which signals a bulk destructive action (terminating all forwards), but it does not clarify required permissions, side effects on existing connections, or behavior when no forwards are active.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no fluff or repetition. Every word earns its place, achieving maximum efficiency for a zero-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no parameters, the description covers the core action adequately. It could mention whether calling the tool multiple times is safe or what happens if no forwards exist, but these are minor gaps for such a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters and 100% coverage. The description adds no parameter-specific detail because none is needed. Baseline 4 is appropriate for tools with no parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Stop') and resource ('all active Kubernetes port-forward processes'), clearly distinguishing it from sibling tools like start_k8s_port_forward (which initiates forwards) and list_k8s_services (which lists services).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use after starting port-forwards or for cleanup, but does not explicitly state when to use versus alternatives. However, the sibling names and the tool's zero-parameter simplicity make the usage context obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
4 tool updates
v1.0.3- First observed
list_k8s_namespaces - First observed
list_k8s_services - First observed
start_k8s_port_forward - First observed
stop_k8s_port_forward
TDQS
Scored across 4 tools
Each tool has a unique and clearly defined purpose: listing services, listing namespaces, starting port forwarding, and stopping all port forwards. No overlap or ambiguity.
All tools follow the consistent snake_case verb_noun pattern (start_k8s_port_forward, list_k8s_services, list_k8s_namespaces, stop_k8s_port_forward), making them predictable and easy to distinguish.
With 4 tools, the server is well-scoped for a focused port-forwarding utility. Each tool is essential: listing services/namespaces, starting, and stopping. No unnecessary bloat.
The core workflow is covered: discover services, start forwarding, stop all. A minor gap is the lack of a tool to list active port forwards or check their status, but the single-session design mitigates this.
Maintenance
Related MCP Connectors
MCP server to assist with JxBrowser development.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
An MCP server that let you interact with Cycloid.io Internal Development Portal and Platform
Related MCP Servers
- FlicenseBqualityDmaintenanceA MCP server that can run Kubernetes commands with a given kubeconfig path and provide interpretation of the commands.14-
- AlicenseNot gradedqualityAmaintenanceA powerful and flexible Kubernetes MCP server implementation with support for OpenShift.2,149GoApache 2.0
- AlicenseNot gradedqualityDmaintenanceMCP of MCPs. Automatic discovery and configure MCP servers on your local machine. Integration with Claude and Cursor.53Apache 2.0
- AlicenseNot gradedqualityBmaintenanceSelf-hosted MCP proxy and aggregation platform. Register multiple upstream MCP servers and expose them through a single unified endpoint with namespace routing, multi-transport support (HTTP/SSE, stdio, OpenAPI→MCP), per-tool overrides, and a web admin UI.18MIT