Kubernetes Port Forward – MCP Server

Servidor MCP que fornece ferramentas para gerenciar sessões de port-forwarding do Kubernetes.

Documentação

Kubernetes Port Forward MCP

Um servidor Model Context Protocol (MCP) que fornece ferramentas para descobrir serviços Kubernetes e executar sessões kubectl port-forward (opcionalmente com janelas de log separadas). Ele é projetado para clientes MCP/LLMs que traduzem linguagem natural em chamadas de ferramentas estruturadas.

Kubernetes Port Forward MCP vs `kubectl port-forward`

Este pacote fornece uma interface MCP sobre o fluxo de trabalho padrão kubectl.

kubectl: Melhor quando você já sabe o namespace/pod/portas exatos e prefere controle manual.
MCP: Melhor quando um agente deve descobrir serviços e executar um ou vários port-forwards via chamadas de ferramentas.

Principais Recursos

Descoberta de serviços: listar namespaces e inferir serviços (nome curto → ambientes → namespace) a partir de pods em execução.
Multi-serviço em uma sessão: iniciar vários port-forwards com uma única chamada de ferramenta.
API amigável para LLM: start_k8s_port_forward aceita um array para que cada serviço possa usar diferentes namespace, environment, localPort e remotePort.
Logs opcionais: abrir kubectl logs -f em uma janela de terminal separada no nível do sistema operacional para cada serviço.

Requisitos

Node.js 18 ou mais recente
kubectl instalado e configurado com acesso ao seu cluster
VS Code, Cursor, Windsurf, Claude Desktop, Cline ou qualquer outro cliente MCP

Início Rápido

Adicione este servidor ao seu cliente MCP (use a configuração em Começando abaixo).
Pergunte ao seu assistente: "Liste os serviços Kubernetes disponíveis."
Pergunte ao seu assistente: "Execute o serviço api na porta local 3002."
Abra a URL retornada (por exemplo http://localhost:3002).
Quando terminar, pergunte: "Pare todos os port-forwards."

Começando

Primeiro, instale o servidor Kubernetes Port Forward MCP com seu cliente.

Configuração padrão funciona na maioria dos clientes MCP:

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

Amp

Adicione via a tela de configurações da extensão Amp VS Code ou atualizando seu arquivo settings.json:

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

Configuração via CLI Amp:

Adicione via o comando amp mcp add abaixo:

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

Antigravity

Adicione via as configurações do Antigravity ou atualizando seu arquivo de configuração:

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

Claude Code

Use a CLI do Claude Code para adicionar o servidor Kubernetes Port Forward MCP:

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

Claude Desktop

Siga o guia de instalação do MCP, use a configuração padrão acima.

Cline

Siga a instrução na seção Configurando Servidores MCP

Exemplo: Configuração Local

Adicione o seguinte ao seu arquivo cline_mcp_settings.json:

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

Codex

Use a CLI do Codex para adicionar o servidor Kubernetes Port Forward MCP:

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

Alternativamente, crie ou edite o arquivo de configuração ~/.codex/config.toml e adicione:

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

Para mais informações, consulte a documentação do Codex MCP.

Copilot

Use a CLI do Copilot para adicionar interativamente o servidor Kubernetes Port Forward MCP:

/mcp add

Alternativamente, crie ou edite o arquivo de configuração ~/.copilot/mcp-config.json e adicione:

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

Para mais informações, consulte a documentação da CLI do Copilot.

Cursor

Clique no botão para instalar:

Ou instale manualmente:

Vá para Cursor Settings -> MCP -> Add new MCP Server. Dê um nome de sua preferência, use o tipo command com o comando npx -y k8s-port-forward-mcp@latest. Você também pode verificar a configuração ou adicionar argumentos de comando clicando em Edit.

Factory

Use a CLI do Factory para adicionar o servidor Kubernetes Port Forward MCP:

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

Alternativamente, digite /mcp dentro do Factory droid para abrir uma interface interativa para gerenciar servidores MCP.

Para mais informações, consulte a documentação do Factory MCP.

Gemini CLI

Siga o guia de instalação do MCP, use a configuração padrão acima.

Goose

Clique no botão para instalar:

Ou instale manualmente:

Vá para Advanced settings -> Extensions -> Add custom extension. Dê um nome de sua preferência, use o tipo STDIO e defina o command para npx -y k8s-port-forward-mcp@latest. Clique em "Adicionar Extensão".

Kiro

Siga a documentação de Servidores MCP. Por exemplo, em .kiro/settings/mcp.json:

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

LM Studio

Clique no botão para instalar:

Ou instale manualmente:

Vá para Program na barra lateral direita -> Install -> Edit mcp.json. Use a configuração padrão acima.

opencode

Siga a documentação de Servidores MCP. Por exemplo, em ~/.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

Abra o painel de chat do Qodo Gen no VSCode ou IntelliJ -> Conecte mais ferramentas -> + Adicionar novo MCP -> Cole a configuração padrão acima.

Clique em Salvar.

VS Code

Clique no botão para instalar:

Ou instale manualmente:

Siga o guia de instalação do MCP, use a configuração padrão acima. Você também pode instalar o servidor Kubernetes Port Forward MCP usando a CLI do VS Code:

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

Após a instalação, o servidor Kubernetes Port Forward MCP estará disponível para uso com seu agente GitHub Copilot no VS Code.

Warp

Vá para Settings -> AI -> Manage MCP Servers -> + Add para adicionar um Servidor MCP. Use a configuração padrão acima.

Alternativamente, use o comando de barra /add-mcp no prompt do Warp e cole a configuração padrão acima:

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

Windsurf

Siga a documentação do Windsurf MCP. Use a configuração padrão acima.

Exemplos

Referência rápida (linguagem natural → chamadas de ferramentas)

"Execute os serviços api e auth nas portas locais 3002, 3003"
→ list_k8s_services({}) e depois start_k8s_port_forward({ services: [{ serviceName: "api", localPort: 3002 }, { serviceName: "auth", localPort: 3003 }] })
"Execute o serviço order do namespace shared services na porta local 3000"
→ start_k8s_port_forward({ services: [{ serviceName: "order", namespace: "shared-services", localPort: 3000 }] })
"Execute o serviço order do namespace shared services e porta remota 3000 na porta local 3000"
→ start_k8s_port_forward({ services: [{ serviceName: "order", namespace: "shared-services", localPort: 3000, remotePort: 3000 }] })
"Execute o serviço api no ambiente qa na porta local 3001"
→ start_k8s_port_forward({ services: [{ serviceName: "api", environment: "qa", localPort: 3001 }] })
"Execute o serviço auth no ambiente prod do namespace production na porta local 3002"
→ start_k8s_port_forward({ services: [{ serviceName: "auth", environment: "prod", namespace: "production", localPort: 3002 }] })
"Pare todos os port-forwards"
→ stop_k8s_port_forward({})

Exemplo de fluxo de trabalho detalhado

Usuário: "Execute o serviço frontend no ambiente qa na porta 3001"

Fluxo de trabalho da IA:

Chame list_k8s_services({}) para encontrar o nome exato do serviço.
Receba uma lista contendo, por exemplo, frontend: qa (ns: ...), dev (ns: ...).
Chame start_k8s_port_forward({ services: [{ serviceName: "frontend", environment: "qa", localPort: 3001 }] }).
Resultado: os port-forwards são executados no processo do servidor MCP; se includeLogs for verdadeiro, os logs abrem em uma janela separada. O resultado da ferramenta inclui http://localhost:3001 e os comandos kubectl exatos.

Ferramentas

Descoberta de serviços

list_k8s_namespaces
- Título: Listar namespaces
- Descrição: Listar todos os namespaces Kubernetes disponíveis.
- Parâmetros: Nenhum
- Somente leitura: true
list_k8s_services
- Título: Listar serviços
- Descrição: Listar serviços disponíveis agrupados por nome curto e ambiente.
- Parâmetros:
  - namespace (string, opcional): Filtrar resultados para um namespace.
- Somente leitura: true

Encaminhamento de porta

start_k8s_port_forward
- Título: Iniciar port-forward
- Descrição: Iniciar o encaminhamento de porta para um ou mais serviços.
- Parâmetros:
  - services (array, obrigatório): Lista de configurações de serviço.
    - serviceName (string, obrigatório): Nome curto do serviço. (Chame list_k8s_services primeiro.)
    - localPort (number, obrigatório): Porta local para vincular (1-65535).
    - namespace (string, opcional): Namespace de destino.
    - remotePort (number, opcional): Porta remota (cluster).
    - environment (string, opcional): dev | qa | stg | prod.
    - includeLogs (boolean, opcional): Se deve abrir logs em uma janela separada (padrão: true).
- Somente leitura: false
stop_k8s_port_forward
- Título: Parar port-forward
- Descrição: Parar todos os processos de port-forward ativos iniciados por este servidor MCP.
- Parâmetros: Nenhum
- Somente leitura: false

Validação e Depuração

Como o servidor MCP inicia processos reais de kubectl em segundo plano, você pode querer verificar o que está em execução e ver os comandos exatos sendo executados.

Verificando processos kubectl em execução

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

Isso ajuda você a:

Verificar se os port-forwards estão realmente em execução
Ver os namespaces e portas exatos em uso
Identificar processos travados que podem precisar de terminação manual
Depurar problemas de conectividade examinando os comandos reais

Falhas comuns e correções

Porta já em uso: escolha outra porta local ou pare o processo conflitante.
Conexão recusada: verifique o nome do serviço, namespace e ambiente selecionado.
Nenhuma janela de logs: defina includeLogs: true na solicitação de port-forward.
Processo travado: termine pelo PID (taskkill /PID <pid> no Windows, kill <pid> no Linux/macOS).

Kubernetes Port Forward – MCP Server

Documentação