Kubernetes Port Forward – MCP Server

Servidor MCP que proporciona herramientas para gestionar sesiones de port-forwarding de Kubernetes.

GitHub

Documentación

Kubernetes Port Forward MCP

Un servidor de Model Context Protocol (MCP) que proporciona herramientas para descubrir servicios de Kubernetes y ejecutar sesiones de kubectl port-forward (opcionalmente con ventanas de registro separadas). Está diseñado para clientes MCP/LLMs que traducen lenguaje natural en llamadas a herramientas estructuradas.

Kubernetes Port Forward MCP vs kubectl port-forward

Este paquete proporciona una interfaz MCP sobre el flujo de trabajo estándar de kubectl.

  • kubectl: Mejor cuando ya conoces el namespace/pod/puertos exactos y prefieres control manual.
  • MCP: Mejor cuando un agente debe descubrir servicios y ejecutar uno o muchos port-forwards mediante llamadas a herramientas.

Características principales

  • Descubrimiento de servicios: lista namespaces e infiere servicios (nombre corto → entornos → namespace) a partir de los pods en ejecución.
  • Multi-servicio en una sola sesión: inicia múltiples port-forwards con una sola llamada a herramienta.
  • API amigable para LLMs: start_k8s_port_forward acepta un array para que cada servicio pueda usar diferentes namespace, environment, localPort y remotePort.
  • Registros opcionales: abre kubectl logs -f en una ventana de terminal separada a nivel de sistema operativo por servicio.

Tabla de contenidos

Requisitos

  • Node.js 18 o superior
  • kubectl instalado y configurado con acceso a tu clúster
  • VS Code, Cursor, Windsurf, Claude Desktop, Cline, o cualquier otro cliente MCP

Inicio rápido

  1. Añade este servidor a tu cliente MCP (usa la configuración en Primeros pasos a continuación).
  2. Pregunta a tu asistente: "Lista los servicios de Kubernetes disponibles."
  3. Pregunta a tu asistente: "Ejecuta el servicio api en el puerto local 3002."
  4. Abre la URL devuelta (por ejemplo http://localhost:3002).
  5. Cuando termines, pregunta: "Detén todos los port-forwards."

Primeros pasos

Primero, instala el servidor Kubernetes Port Forward MCP con tu cliente.

Configuración estándar funciona en la mayoría de los clientes MCP:

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

Install in VS Code Install in VS Code Insiders

Amp

Añade mediante la pantalla de configuración de la extensión Amp de VS Code o actualizando tu archivo settings.json:

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

Configuración CLI de Amp:

Añade mediante el comando amp mcp add a continuación:

amp mcp add k8s-port-forward -- npx -y k8s-port-forward-mcp@latest
Antigravity

Añade mediante la configuración de Antigravity o actualizando tu archivo de configuración:

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

Usa la CLI de Claude Code para añadir el servidor Kubernetes Port Forward MCP:

claude mcp add k8s-port-forward npx -y k8s-port-forward-mcp@latest
Claude Desktop

Sigue la guía de instalación de MCP, usa la configuración estándar anterior.

Cline

Sigue las instrucciones en la sección Configurando servidores MCP

Ejemplo: Configuración local

Añade lo siguiente a tu archivo cline_mcp_settings.json:

{
  "mcpServers": {
    "k8s-port-forward": {
      "type": "stdio",
      "command": "npx",
      "timeout": 30,
      "args": ["-y", "k8s-port-forward-mcp@latest"],
      "disabled": false
    }
  }
}
Codex

Usa la CLI de Codex para añadir el servidor Kubernetes Port Forward MCP:

codex mcp add k8s-port-forward npx "-y" "k8s-port-forward-mcp@latest"

Alternativamente, crea o edita el archivo de configuración ~/.codex/config.toml y añade:

[mcp_servers.k8s-port-forward]
command = "npx"
args = ["-y", "k8s-port-forward-mcp@latest"]

Para más información, consulta la documentación de MCP de Codex.

Copilot

Usa la CLI de Copilot para añadir interactivamente el servidor Kubernetes Port Forward MCP:

/mcp add

Alternativamente, crea o edita el archivo de configuración ~/.copilot/mcp-config.json y añade:

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

Para más información, consulta la documentación de la CLI de Copilot.

Cursor

Haz clic en el botón para instalar:

Install in Cursor

O instala manualmente:

Ve a Cursor Settings -> MCP -> Add new MCP Server. Ponle el nombre que prefieras, usa el tipo command con el comando npx -y k8s-port-forward-mcp@latest. También puedes verificar la configuración o añadir argumentos de comando haciendo clic en Edit.

Factory

Usa la CLI de Factory para añadir el servidor Kubernetes Port Forward MCP:

droid mcp add k8s-port-forward "npx -y k8s-port-forward-mcp@latest"

Alternativamente, escribe /mcp dentro de Factory droid para abrir una interfaz interactiva para gestionar servidores MCP.

Para más información, consulta la documentación de MCP de Factory.

Gemini CLI

Sigue la guía de instalación de MCP, usa la configuración estándar anterior.

Goose

Haz clic en el botón para instalar:

Install in Goose

O instala manualmente:

Ve a Advanced settings -> Extensions -> Add custom extension. Ponle el nombre que prefieras, usa el tipo STDIO y establece el command a npx -y k8s-port-forward-mcp@latest. Haz clic en "Add Extension".

Kiro

Sigue la documentación de Servidores MCP. Por ejemplo en .kiro/settings/mcp.json:

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

Haz clic en el botón para instalar:

Add MCP Server k8s-port-forward to LM Studio

O instala manualmente:

Ve a Program en la barra lateral derecha -> Install -> Edit mcp.json. Usa la configuración estándar anterior.

opencode

Sigue la documentación de Servidores MCP. Por ejemplo en ~/.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

Abre el panel de chat de Qodo Gen en VSCode o IntelliJ -> Connect more tools -> + Add new MCP -> Pega la configuración estándar anterior.

Haz clic en Guardar.

VS Code

Haz clic en el botón para instalar:

Install in VS Code Install in VS Code Insiders

O instala manualmente:

Sigue la guía de instalación de MCP, usa la configuración estándar anterior. También puedes instalar el servidor Kubernetes Port Forward MCP usando la CLI de VS Code:

# For VS Code
code --add-mcp '{"name":"k8s-port-forward","command":"npx","args":["-y","k8s-port-forward-mcp@latest"]}'

Después de la instalación, el servidor Kubernetes Port Forward MCP estará disponible para usarse con tu agente GitHub Copilot en VS Code.

Warp

Ve a Settings -> AI -> Manage MCP Servers -> + Add para añadir un servidor MCP. Usa la configuración estándar anterior.

Alternativamente, usa el comando de barra /add-mcp en el prompt de Warp y pega la configuración estándar anterior:

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

Sigue la documentación de MCP de Windsurf. Usa la configuración estándar anterior.

Ejemplos

Referencia rápida (lenguaje natural → llamadas a herramientas)

  • "Ejecuta los servicios api y auth en los puertos locales 3002, 3003"
    → list_k8s_services({}) y luego start_k8s_port_forward({ services: [{ serviceName: "api", localPort: 3002 }, { serviceName: "auth", localPort: 3003 }] })

  • "Ejecuta el servicio order desde el namespace shared services en el puerto local 3000"
    → start_k8s_port_forward({ services: [{ serviceName: "order", namespace: "shared-services", localPort: 3000 }] })

  • "Ejecuta el servicio order desde el namespace shared services y el puerto remoto 3000 en el puerto local 3000"
    → start_k8s_port_forward({ services: [{ serviceName: "order", namespace: "shared-services", localPort: 3000, remotePort: 3000 }] })

  • "Ejecuta el servicio api en el entorno qa en el puerto local 3001"
    → start_k8s_port_forward({ services: [{ serviceName: "api", environment: "qa", localPort: 3001 }] })

  • "Ejecuta el servicio auth en el entorno prod desde el namespace production en el puerto local 3002"
    → start_k8s_port_forward({ services: [{ serviceName: "auth", environment: "prod", namespace: "production", localPort: 3002 }] })

  • "Detén todos los port-forwards"
    → stop_k8s_port_forward({})

Ejemplo de flujo de trabajo detallado

Usuario: "Ejecuta el servicio frontend en qa en el puerto 3001"

Flujo de trabajo de la IA:

  1. Llama a list_k8s_services({}) para encontrar el nombre exacto del servicio.
  2. Recibe la lista que contiene, por ejemplo, frontend: qa (ns: ...), dev (ns: ...).
  3. Llama a start_k8s_port_forward({ services: [{ serviceName: "frontend", environment: "qa", localPort: 3001 }] }).
  4. Resultado: los port-forwards se ejecutan en el proceso del servidor MCP; si includeLogs es true, los registros se abren en una ventana separada. El resultado de la herramienta incluye http://localhost:3001 y los comandos kubectl exactos.

Herramientas

Descubrimiento de servicios

  • list_k8s_namespaces

    • Título: Listar namespaces
    • Descripción: Lista todos los namespaces de Kubernetes disponibles.
    • Parámetros: Ninguno
    • Solo lectura: true

  • list_k8s_services

    • Título: Listar servicios
    • Descripción: Lista los servicios disponibles agrupados por nombre corto y entorno.
    • Parámetros:
      • namespace (string, opcional): Filtra los resultados a un namespace.
    • Solo lectura: true
Reenvío de puertos

  • start_k8s_port_forward

    • Título: Iniciar port-forward
    • Descripción: Inicia el reenvío de puertos para uno o más servicios.
    • Parámetros:
      • services (array, obligatorio): Lista de configuraciones de servicios.
        • serviceName (string, obligatorio): Nombre corto del servicio. (Llama a list_k8s_services primero.)
        • localPort (number, obligatorio): Puerto local a vincular (1-65535).
        • namespace (string, opcional): Namespace de destino.
        • remotePort (number, opcional): Puerto remoto (del clúster).
        • environment (string, opcional): dev | qa | stg | prod.
        • includeLogs (boolean, opcional): Si se deben abrir los registros en una ventana separada (por defecto: true).
    • Solo lectura: false

  • stop_k8s_port_forward

    • Título: Detener port-forward
    • Descripción: Detiene todos los procesos de port-forward activos iniciados por este servidor MCP.
    • Parámetros: Ninguno
    • Solo lectura: false

Validación y depuración

Dado que el servidor MCP genera procesos reales de kubectl en segundo plano, es posible que quieras verificar qué se está ejecutando y ver los comandos exactos que se están ejecutando.

Comprobando procesos kubectl en ejecución

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

Esto te ayuda a:

  • Verificar que los port-forwards realmente se están ejecutando
  • Ver los namespaces y puertos exactos que se están usando
  • Identificar procesos bloqueados que podrían necesitar terminación manual
  • Depurar problemas de conectividad examinando los comandos reales

Fallos comunes y soluciones

  • Puerto ya en uso: elige otro puerto local o detén el proceso en conflicto.
  • Conexión rechazada: verifica el nombre del servicio, el namespace y el entorno seleccionado.
  • Sin ventana de registros: establece includeLogs: true en la solicitud de port-forward.
  • Proceso bloqueado: termínalo por PID (taskkill /PID <pid> en Windows, kill <pid> en Linux/macOS).