Summary
This server wraps kubectl port-forward into a set of MCP tools so Claude can discover services in your cluster and spin up local tunnels without you copying pod names or namespaces. It exposes tools to list namespaces, infer service names from running pods, and start multiple port-forwards in one call with custom local and remote ports. You can optionally open separate terminal windows streaming kubectl logs for each service. It's built for workflows where you want to ask "forward the api service to port 3002" instead of hunting down the exact pod and typing the kubectl command yourself. Requires Node.js and a configured kubectl context.
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
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.
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
- Quick Start
- Getting Started
- Examples
- Tools
- Output and Logs
- Configuration
- Validation and Debugging
Requirements
- Node.js 18 or newer
kubectlinstalled and configured with access to your cluster- VS 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"]
}
}
}
Amp
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@latest
Antigravity
Add via the Antigravity settings or by updating your configuration file:
{
"mcpServers": {
"k8s-port-forward": {
"command": "npx",
"args": ["-y", "k8s-port-forward-mcp@latest"]
}
}
}
Claude Code
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@latest
Claude Desktop
Follow the MCP install guide, use the standard config above.
Cline
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
}
}
}
Codex
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.
Copilot
Use the Copilot CLI to interactively add the Kubernetes Port Forward MCP server:
/mcp add
Alternatively, 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.
Cursor
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.
Factory
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.
Gemini CLI
Follow the MCP install guide, use the standard config above.
Goose
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".
Kiro
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"]
}
}
}
LM Studio
Click the button to install:
Or install manually:
Go to Program in the right sidebar -> Install -> Edit mcp.json. Use the standard config above.
opencode
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
}
}
}
Qodo Gen
Open Qodo Gen chat panel in VSCode or IntelliJ -> Connect more tools -> + Add new MCP -> Paste the standard config above.
Click Save.
VS Code
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.
Warp
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"
]
}
}
}
Windsurf
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
Service discovery
-
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
Port forwarding
-
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,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: truein the port-forward request. - Stuck process: terminate by PID (
taskkill /PID <pid>on Windows,kill <pid>on Linux/macOS).
Featured
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →Categories
Registryactive
Packagek8s-port-forward-mcp
TransportSTDIO
UpdatedFeb 24, 2026
