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_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.

Table of Contents

• Requirements
• Quick Start
• Getting Started
• Examples
• Tools
• Output and Logs
• Configuration
• Validation and Debugging

Requirements

• Node.js 18 or newer
• kubectl installed and configured with access to your cluster
• VS Code, Cursor, Windsurf, Claude Desktop, Cline, or any other MCP client

Quick Start

1. Add this server to your MCP client (use the config in Getting Started below).
2. Ask your assistant: "List available Kubernetes services."
3. Ask your assistant: "Run api service on local port 3002."
4. Open the returned URL (for example http://localhost:3002).
5. 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"]
    }
  }
}

<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="Install in VS Code"> <img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">

<details> <summary>Amp</summary>

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

</details>

<details> <summary>Antigravity</summary>

Add via the Antigravity settings or by updating your configuration file:

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

</details>

<details> <summary>Claude Code</summary>

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

</details>

<details> <summary>Claude Desktop</summary>

Follow the MCP install guide, use the standard config above.

</details>

<details> <summary>Cline</summary>

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
    }
  }
}

</details>

<details> <summary>Codex</summary>

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.

</details>

<details> <summary>Copilot</summary>

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.

</details>

<details> <summary>Cursor</summary>

#### Click the button to install:

<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor">

#### 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.

</details>

<details> <summary>Factory</summary>

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.

</details>

<details> <summary>Gemini CLI</summary>

Follow the MCP install guide, use the standard config above.

</details>

<details> <summary>Goose</summary>

#### 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".

</details>

<details> <summary>Kiro</summary>

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"]
    }
  }
}

</details>

<details> <summary>LM Studio</summary>

#### Click the button to install:

#### Or install manually:

Go to Program in the right sidebar -> Install -> Edit mcp.json. Use the standard config above.

</details>

<details> <summary>opencode</summary>

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
    }
  }
}

</details>

<details> <summary>Qodo Gen</summary>

Open Qodo Gen chat panel in VSCode or IntelliJ -> Connect more tools -> + Add new MCP -> Paste the standard config above.

Click <code>Save</code>.

</details>

<details> <summary>VS Code</summary>

#### Click the button to install:

<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="Install in VS Code"> <img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">

#### 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.

</details>

<details> <summary>Warp</summary>

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"
      ]
    }
  }
}

</details>

<details> <summary>Windsurf</summary>

Follow Windsurf MCP documentation. Use the standard config above.

</details>

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:

1. Call list_k8s_services({}) to find the exact service name.
2. Receive list containing e.g. frontend: qa (ns: ...), dev (ns: ...).
3. Call start_k8s_port_forward({ services: [{ serviceName: "frontend", environment: "qa", localPort: 3001 }] }).
4. 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

<details> <summary><b>Service discovery</b></summary>

• 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

</details>

<details> <summary><b>Port forwarding</b></summary>

• 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.
• 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

</details>

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).