Kubernetes Port Forward MCP
Provides tools for discovering Kubernetes services and running kubectl port-forward sessions to access them locally.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Kubernetes Port Forward MCPRun api service on local port 3002"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Kubernetes Port Forward MCP
A Model Context Protocol (MCP) server that provides tools for discovering Kubernetes services and running kubectl port-forward sessions (optionally with separate log windows). It is designed for MCP clients/LLMs that translate natural language into structured tool calls.
Kubernetes Port Forward MCP vs kubectl port-forward
This package provides an MCP interface on top of the standard kubectl workflow.
kubectl: Best when you already know exact namespace/pod/ports and prefer manual control.MCP: Best when an agent should discover services and run one or many port-forwards via tool calls.
Related MCP server: kubernetes-mcp-server
Key Features
Service discovery: list namespaces and infer services (short name → environments → namespace) from running pods.
Multi-service in one session: start multiple port-forwards with one tool call.
LLM-friendly API:
start_k8s_port_forwardaccepts an array so each service can use differentnamespace,environment,localPort, andremotePort.Optional logs: open
kubectl logs -fin a separate OS-level terminal window per service.
Table of Contents
Requirements
Node.js 18 or newer
kubectlinstalled and configured with access to your clusterVS Code, Cursor, Windsurf, Claude Desktop, Cline, or any other MCP client
Quick Start
Add this server to your MCP client (use the config in Getting Started below).
Ask your assistant: "List available Kubernetes services."
Ask your assistant: "Run api service on local port 3002."
Open the returned URL (for example
http://localhost:3002).When finished, ask: "Stop all port-forwards."
Getting Started
First, install the Kubernetes Port Forward MCP server with your client.
Standard config works in most MCP clients:
{
"mcpServers": {
"k8s-port-forward": {
"command": "npx",
"args": ["-y", "k8s-port-forward-mcp@latest"]
}
}
}
Add via the Amp VS Code extension settings screen or by updating your settings.json file:
"amp.mcpServers": {
"k8s-port-forward": {
"command": "npx",
"args": [
"-y",
"k8s-port-forward-mcp@latest"
]
}
}Amp CLI Setup:
Add via the amp mcp add command below:
amp mcp add k8s-port-forward -- npx -y k8s-port-forward-mcp@latestAdd via the Antigravity settings or by updating your configuration file:
{
"mcpServers": {
"k8s-port-forward": {
"command": "npx",
"args": ["-y", "k8s-port-forward-mcp@latest"]
}
}
}Use the Claude Code CLI to add the Kubernetes Port Forward MCP server:
claude mcp add k8s-port-forward npx -y k8s-port-forward-mcp@latestFollow the MCP install guide, use the standard config above.
Follow the instruction in the section Configuring MCP Servers
Example: Local Setup
Add the following to your cline_mcp_settings.json file:
{
"mcpServers": {
"k8s-port-forward": {
"type": "stdio",
"command": "npx",
"timeout": 30,
"args": ["-y", "k8s-port-forward-mcp@latest"],
"disabled": false
}
}
}Use the Codex CLI to add the Kubernetes Port Forward MCP server:
codex mcp add k8s-port-forward npx "-y" "k8s-port-forward-mcp@latest"Alternatively, create or edit the configuration file ~/.codex/config.toml and add:
[mcp_servers.k8s-port-forward]
command = "npx"
args = ["-y", "k8s-port-forward-mcp@latest"]For more information, see the Codex MCP documentation.
Use the Copilot CLI to interactively add the Kubernetes Port Forward MCP server:
/mcp addAlternatively, create or edit the configuration file ~/.copilot/mcp-config.json and add:
{
"mcpServers": {
"k8s-port-forward": {
"type": "local",
"command": "npx",
"tools": ["*"],
"args": ["-y", "k8s-port-forward-mcp@latest"]
}
}
}For more information, see the Copilot CLI documentation.
Click the button to install:
Or install manually:
Go to Cursor Settings -> MCP -> Add new MCP Server. Name to your liking, use command type with the command npx -y k8s-port-forward-mcp@latest. You can also verify config or add command arguments via clicking Edit.
Use the Factory CLI to add the Kubernetes Port Forward MCP server:
droid mcp add k8s-port-forward "npx -y k8s-port-forward-mcp@latest"Alternatively, type /mcp within Factory droid to open an interactive UI for managing MCP servers.
For more information, see the Factory MCP documentation.
Follow the MCP install guide, use the standard config above.
Click the button to install:
Or install manually:
Go to Advanced settings -> Extensions -> Add custom extension. Name to your liking, use type STDIO, and set the command to npx -y k8s-port-forward-mcp@latest. Click "Add Extension".
Follow the MCP Servers documentation. For example in .kiro/settings/mcp.json:
{
"mcpServers": {
"k8s-port-forward": {
"command": "npx",
"args": ["-y", "k8s-port-forward-mcp@latest"]
}
}
}Click the button to install:
Or install manually:
Go to Program in the right sidebar -> Install -> Edit mcp.json. Use the standard config above.
Follow the MCP Servers documentation. For example in ~/.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
}
}
}Open Qodo Gen chat panel in VSCode or IntelliJ -> Connect more tools -> + Add new MCP -> Paste the standard config above.
Click Save.
Click the button to install:
Or install manually:
Follow the MCP install guide, use the standard config above. You can also install the Kubernetes Port Forward MCP server using the VS Code CLI:
# For VS Code
code --add-mcp '{"name":"k8s-port-forward","command":"npx","args":["-y","k8s-port-forward-mcp@latest"]}'After installation, the Kubernetes Port Forward MCP server will be available for use with your GitHub Copilot agent in VS Code.
Go to Settings -> AI -> Manage MCP Servers -> + Add to add an MCP Server. Use the standard config above.
Alternatively, use the slash command /add-mcp in the Warp prompt and paste the standard config from above:
{
"mcpServers": {
"k8s-port-forward": {
"command": "npx",
"args": [
"-y",
"k8s-port-forward-mcp@latest"
]
}
}
}Follow Windsurf MCP documentation. Use the standard config above.
Examples
Quick reference (natural language → tool calls)
"Run api and auth services on local ports 3002, 3003"
→list_k8s_services({})thenstart_k8s_port_forward({ services: [{ serviceName: "api", localPort: 3002 }, { serviceName: "auth", localPort: 3003 }] })"Run order service from shared services namespace in local port 3000"
→start_k8s_port_forward({ services: [{ serviceName: "order", namespace: "shared-services", localPort: 3000 }] })"Run order service from shared services namespace and remote port 3000 in local port 3000"
→start_k8s_port_forward({ services: [{ serviceName: "order", namespace: "shared-services", localPort: 3000, remotePort: 3000 }] })"Run api service in qa environment on local port 3001"
→start_k8s_port_forward({ services: [{ serviceName: "api", environment: "qa", localPort: 3001 }] })"Run auth service in prod environment from production namespace on local port 3002"
→start_k8s_port_forward({ services: [{ serviceName: "auth", environment: "prod", namespace: "production", localPort: 3002 }] })"Stop all port-forwards"
→stop_k8s_port_forward({})
Detailed workflow example
User: "Run the frontend service in qa on port 3001"
AI workflow:
Call
list_k8s_services({})to find the exact service name.Receive list containing e.g.
frontend: qa (ns: ...), dev (ns: ...).Call
start_k8s_port_forward({ services: [{ serviceName: "frontend", environment: "qa", localPort: 3001 }] }).Result: port-forwards run in the MCP server process; if
includeLogsis true, logs open in a separate window. The tool result includeshttp://localhost:3001and the exact kubectl commands.
Tools
list_k8s_namespaces
Title: List namespaces
Description: List all available Kubernetes namespaces.
Parameters: None
Read-only: true
list_k8s_services
Title: List services
Description: List available services grouped by short name and environment.
Parameters:
namespace(string, optional): Filter results to a namespace.
Read-only: true
start_k8s_port_forward
Title: Start port-forward
Description: Start port-forwarding for one or more services.
Parameters:
services(array, required): List of service configs.serviceName(string, required): Short name of the service. (Calllist_k8s_servicesfirst.)localPort(number, required): Local port to bind (1-65535).namespace(string, optional): Namespace to target.remotePort(number, optional): Remote (cluster) port.environment(string, optional):dev|qa|stg|prod.includeLogs(boolean, optional): Whether to open logs in a separate window (default: true).
Read-only: false
stop_k8s_port_forward
Title: Stop port-forward
Description: Stop all active port-forward processes started by this MCP server.
Parameters: None
Read-only: false
Validation and Debugging
Since the MCP server spawns actual kubectl processes in the background, you may want to verify what's running and see the exact commands being executed.
Checking running kubectl processes
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 kubectlThis helps you:
Verify port-forwards are actually running
See the exact namespaces and ports being used
Identify stuck processes that might need manual termination
Debug connectivity issues by examining the actual commands
Common failures and fixes
Port already in use: choose another local port or stop the conflicting process.
Connection refused: verify service name, namespace, and selected environment.
No logs window: set
includeLogs: truein the port-forward request.Stuck process: terminate by PID (
taskkill /PID <pid>on Windows,kill <pid>on Linux/macOS).
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. Dates show when Glama detected each change.
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
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
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
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,057GoApache 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.17MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/oijusti/k8s-port-forward-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server