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

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

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

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

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