How to add kubefwd to Windsurf

Bulk Kubernetes port forwarding with an MCP server that lets AI assistants forward services, inspect pods, and monitor traffic. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 4.1k★ · stdio · no auth · official

Windsurf config for kubefwd

brew install kubefwd

{
  "mcpServers": {
    "kubefwd": {
      "command": "kubefwd",
      "args": [
        "mcp"
      ]
    }
  }
}

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the kubefwd config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5kubefwd's tools become available to Cascade.

Before you start

kubefwd installed and on your PATH (brew install kubefwd, winget/scoop on Windows, or .deb/.rpm/.tar.gz from GitHub releases)
kubectl configured with cluster access (a valid kubeconfig)
Root/sudo access to run kubefwd itself (for /etc/hosts and network interfaces)
kubefwd running with the API enabled so the MCP bridge can reach it, e.g. `sudo -E kubefwd --api` or `sudo -E kubefwd --tui`

What kubefwd can do in Windsurf

list_k8s_namespaces

List available Kubernetes namespaces and which are forwarded.

list_k8s_services

List services in a namespace with their types, ports, and selectors.

list_contexts

List available Kubernetes contexts (clusters) from your kubeconfig.

add_namespace

Forward all services in a namespace to localhost with automatic /etc/hosts entries.

remove_namespace

Stop forwarding an entire namespace.

add_service

Forward a specific service, optionally with custom port mappings.

remove_service

Stop forwarding an individual service.

list_services

List currently forwarded services.

Security

kubefwd itself requires root/sudo to modify /etc/hosts and create loopback network interfaces, but the MCP bridge (kubefwd mcp) runs as a standard user with no elevated privileges. The kubefwd REST API binds to localhost by default, so forwards are only reachable on your machine. kubefwd uses your existing kubeconfig; no cluster credentials are passed through MCP. Exposing the API via a public tunnel (e.g. ngrok, required for ChatGPT/remote HTTP-SSE clients) gives external access to your forwards and should only be done in development with tunnel authentication enabled.

kubefwd + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the kubefwd config there under the "mcpServers" key and restart the client.

Is kubefwd safe to use with Windsurf?

How do I add the kubefwd MCP server to Claude Code?

Run `claude mcp add --transport stdio kubefwd -- kubefwd mcp`, then verify with `claude mcp list`. Claude Code spawns `kubefwd mcp` automatically when needed. kubefwd itself must already be running with the API enabled (e.g. `sudo -E kubefwd --api` or `sudo -E kubefwd --tui`).

What transport does it use, and does my AI client need root?

It uses stdio transport. The MCP bridge (kubefwd mcp) runs as a standard, unprivileged user and talks to the privileged kubefwd process over its localhost REST API, so your AI client never needs sudo. Only the main kubefwd process requires root for /etc/hosts and network interface changes.

Does kubefwd MCP need any API keys or credentials?

No. kubefwd uses your existing kubeconfig for cluster access, and no credentials are passed through MCP. The MCP config is just the `kubefwd` command with the `mcp` argument.

View repo Full kubefwd page