Kubernetes Port Forward MCP

Kubernetes 서비스를 검색하고 kubectl port-forward 세션(선택적으로 별도의 로그 창 포함)을 실행할 수 있는 도구를 제공하는 Model Context Protocol(MCP) 서버입니다. 자연어를 구조화된 도구 호출로 변환하는 MCP 클라이언트/LLM을 위해 설계되었습니다.

Kubernetes Port Forward MCP vs kubectl port-forward

이 패키지는 표준 kubectl 워크플로 위에 MCP 인터페이스를 제공합니다.

• kubectl: 정확한 네임스페이스/파드/포트를 이미 알고 있고 수동 제어를 선호할 때 가장 적합합니다.

• MCP: 에이전트가 서비스를 검색하고 도구 호출을 통해 하나 또는 여러 개의 포트 포워드를 실행해야 할 때 가장 적합합니다.

Related MCP server: kubernetes-mcp-server

주요 기능

• 서비스 검색: 네임스페이스를 나열하고 실행 중인 파드에서 서비스(짧은 이름 → 환경 → 네임스페이스)를 유추합니다.

• 단일 세션에서 다중 서비스: 하나의 도구 호출로 여러 포트 포워드를 시작합니다.

• 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 클라이언트

빠른 시작

1. 이 서버를 MCP 클라이언트에 추가합니다(아래 시작하기의 구성을 사용).

2. 어시스턴트에게 "사용 가능한 Kubernetes 서비스 목록을 보여줘."라고 요청합니다.

3. 어시스턴트에게 "로컬 포트 3002에서 api 서비스를 실행해."라고 요청합니다.

4. 반환된 URL(예: http://localhost:3002)을 엽니다.

5. 완료되면 "모든 포트 포워드를 중지해."라고 요청합니다.

시작하기

먼저 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로 설정합니다. "Add Extension"을 클릭합니다.

MCP 서버 문서를 따릅니다. 예를 들어 .kiro/settings/mcp.json 파일에 다음과 같이 작성합니다.

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

버튼을 클릭하여 설치합니다.

또는 수동으로 설치합니다.

오른쪽 사이드바의 Program -> Install -> Edit mcp.json으로 이동합니다. 위의 표준 구성을 사용합니다.

MCP 서버 문서를 따릅니다. 예를 들어 ~/.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 채팅 패널을 엽니다 -> Connect more tools -> + Add new 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 문서를 따릅니다. 위의 표준 구성을 사용합니다.

예제

빠른 참조(자연어 → 도구 호출)

• "api 및 auth 서비스를 로컬 포트 3002, 3003에서 실행해"
  → list_k8s_services({}) 후 start_k8s_port_forward({ services: [{ serviceName: "api", localPort: 3002 }, { serviceName: "auth", localPort: 3003 }] })

• "shared services 네임스페이스의 order 서비스를 로컬 포트 3000에서 실행해"
  → start_k8s_port_forward({ services: [{ serviceName: "order", namespace: "shared-services", localPort: 3000 }] })

• "shared services 네임스페이스의 order 서비스를 원격 포트 3000에서 로컬 포트 3000으로 실행해"
  → start_k8s_port_forward({ services: [{ serviceName: "order", namespace: "shared-services", localPort: 3000, remotePort: 3000 }] })

• "qa 환경의 api 서비스를 로컬 포트 3001에서 실행해"
  → start_k8s_port_forward({ services: [{ serviceName: "api", environment: "qa", localPort: 3001 }] })

• "production 네임스페이스의 prod 환경에서 auth 서비스를 로컬 포트 3002로 실행해"
  → start_k8s_port_forward({ services: [{ serviceName: "auth", environment: "prod", namespace: "production", localPort: 3002 }] })

• "모든 포트 포워드 중지"
  → stop_k8s_port_forward({})

상세 워크플로 예제

사용자: "포트 3001에서 qa의 frontend 서비스를 실행해"

AI 워크플로:

1. list_k8s_services({})를 호출하여 정확한 서비스 이름을 찾습니다.

2. 예: frontend: qa (ns: ...), dev (ns: ...)가 포함된 목록을 받습니다.

3. start_k8s_port_forward({ services: [{ serviceName: "frontend", environment: "qa", localPort: 3001 }] })를 호출합니다.

4. 결과: 포트 포워드는 MCP 서버 프로세스에서 실행됩니다. includeLogs가 true이면 로그가 별도 창에서 열립니다. 도구 결과에는 http://localhost:3001과 정확한 kubectl 명령이 포함됩니다.

도구

• list_k8s_namespaces

  • 제목: 네임스페이스 나열

  • 설명: 사용 가능한 모든 Kubernetes 네임스페이스를 나열합니다.

  • 매개변수: 없음

  • 읽기 전용: true

• list_k8s_services

  • 제목: 서비스 나열

  • 설명: 짧은 이름과 환경별로 그룹화된 사용 가능한 서비스를 나열합니다.

  • 매개변수:

    • namespace (문자열, 선택 사항): 결과를 특정 네임스페이스로 필터링합니다.

  • 읽기 전용: true

• start_k8s_port_forward

  • 제목: 포트 포워딩 시작

  • 설명: 하나 이상의 서비스에 대한 포트 포워딩을 시작합니다.

  • 매개변수:

    • services (array, required): 서비스 구성 목록입니다.

      • serviceName (string, required): 서비스의 짧은 이름입니다. (먼저 list_k8s_services를 호출하세요.)

      • localPort (number, required): 바인딩할 로컬 포트(1-65535)입니다.

      • namespace (string, optional): 대상 네임스페이스입니다.

      • remotePort (number, optional): 원격(클러스터) 포트입니다.

      • environment (string, optional): dev | qa | stg | prod.

      • includeLogs (boolean, optional): 별도 창에서 로그를 열지 여부(기본값: true)입니다.

  • 읽기 전용: false

• stop_k8s_port_forward

  • 제목: 포트 포워딩 중지

  • 설명: 이 MCP 서버에서 시작한 모든 활성 포트 포워딩 프로세스를 중지합니다.

  • 매개변수: 없음

  • 읽기 전용: 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,CommandLine

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