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
Kubernetes Port Forward — MCP Server: port-forward Kubernetes services with terminal integration
2026-11-10
ดาว
—
เครื่องมือ
—
อัปไทม์
—
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.
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_forward accepts an array so each service can use different namespace, environment, localPort, and remotePort.
Optional logs: open kubectl logs -f in a separate OS-level terminal window per service.
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:
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:
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({}) then start_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: ...).
Result: port-forwards run in the MCP server process; if includeLogs is true, logs open in a separate window. The tool result includes http://localhost:3001 and 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. (Call list_k8s_services first.)
localPort (number, required): Local port to bind (1-65535).
namespace (string, optional): Namespace to target.
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,CommandLine
Linux/macOS:
# List all kubectl processes
ps aux | grep kubectl
# See the exact commands with process IDs
ps -ef | grep kubectl
This 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: true in the port-forward request.
Stuck process: terminate by PID (taskkill /PID <pid> on Windows, kill <pid> on Linux/macOS).