kubefwd

Official

Bulk Kubernetes port forwarding with an MCP server that lets AI assistants forward services, inspect pods, and monitor traffic.

Unverified

stdio (local)

No auth

View repo 4.1k Website

Add to your client

Copy the config for your MCP client and paste it into its config file.

Install / run

brew install kubefwd

Paste into ~/Library/Application Support/Claude/claude_desktop_config.json

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

Step-by-step guides: Add to Claude Desktop · Add to Cursor · Add to Windsurf

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`

About kubefwd

kubefwd is a Go CLI that bulk port forwards all services in one or more Kubernetes namespaces to your local machine, assigning each service a unique 127.x.x.x loopback IP and registering its name in /etc/hosts so existing in-cluster connection strings (e.g. http://api-gateway:8080, db:5432) work unchanged locally. It includes an interactive TUI, auto-reconnect, live traffic metrics, pod log streaming, and a REST API. Its MCP server — started with the kubefwd mcp subcommand — bridges AI assistants to the running kubefwd process over stdio, communicating with the privileged forwarding engine through the localhost REST API. AI clients can then forward/remove services, query the cluster, fetch connection info, inspect pods, monitor traffic, and troubleshoot, all without needing root.

Tools & capabilities (28)

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.

get_service

Get details about a specific forwarded service.

find_services

Search forwarded services by name pattern, port, or namespace.

get_connection_info

Get ready-to-use connection strings, IPs, hostnames, and environment variables for forwarded services.

list_hostnames

List host mappings for forwarded services.

list_pods

List pods with status, ready state, restarts, and age; filter by labels or service.

get_pod

Inspect a pod's containers, conditions, resources, and recent events.

get_pod_logs

Stream logs from containers with tail, timestamps, and time filtering.

get_events

View Kubernetes scheduling, pulling, and starting events for diagnosing failures.

get_endpoints

See which pods back a service and their ready state.

get_health

Report kubefwd system health.

get_quick_status

Fast health check of kubefwd (healthy/degraded/unhealthy).

get_metrics

Bandwidth stats: bytes in/out, transfer rates, and per-service breakdown.

get_analysis

Full issue classification with priorities and recommended actions.

diagnose_errors

Root cause analysis of errors with specific fix suggestions.

get_http_traffic

View HTTP requests flowing through forwards (method, path, status code, response time).

get_history

Track events, errors, and reconnections over time.

get_logs

View kubefwd logs filtered by level (debug, info, warn, error) or search terms.

reconnect_service

Force reconnection for an errored or stale service.

reconnect_all_errors

Force reconnection for all services currently in an error state.

sync_service

Re-discover pods after deployments or pod restarts.

What this server can do

kubefwd provides tools for these capabilities — tap one to see every MCP server that does the same:

Deploy & manage cloud infra

When to use it

Tell an AI assistant 'I need the staging database' and have it forward the service and return a ready-to-use connection string.
Set up a full local development environment by forwarding all services in a namespace so existing in-cluster connection strings work unchanged on your laptop.
Test a freshly deployed API and have the assistant report health checks, request rates, and pod logs.
Debug failing connections by letting the AI diagnose stale or errored forwards and reconnect them.
Compare a service across multiple clusters by forwarding it from dev and staging simultaneously.

Security notes

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 FAQ

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.

Can I use it with ChatGPT?

Only indirectly. ChatGPT supports MCP solely via remote HTTP/SSE servers and cannot reach localhost, so you must expose kubefwd's REST API through a tunnel like ngrok (`sudo -E kubefwd --api` then `ngrok http 8080`). This exposes your forwards externally, so use it only in development with tunnel authentication enabled. Desktop clients (Claude Code/Desktop, Cursor, Windsurf, VS Code, Zed, JetBrains, Cline, Gemini CLI) use stdio directly.

What can the AI do beyond the 28 tools?

The MCP server also exposes 8 read-only resources (e.g. kubefwd://status, kubefwd://services, kubefwd://metrics, kubefwd://http-traffic, kubefwd://contexts) and 10 guided prompts (e.g. setup_local_dev, forward_namespace, quick_connect, troubleshoot, debug_service, fix_errors, monitor).

#kubernetes #port-forwarding #devops #k8s #networking #local-development #cli #tui

Alternatives to kubefwd

Compare all alternatives →

GitHub MCP Server

DevOps & Cloud

31k

GitHub's official server for repos, issues, PRs, and Actions — local Docker or hosted remote.

Featured

Verified

stdio (local)

API key

7 tools

Updated 7 days agoRepo

AWS API MCP Server

DevOps & Cloud

9.3k

Official AWS Labs server that lets agents call any AWS API via the AWS CLI surface.

Verified

stdio (local)

API key

Python

3 tools

Updated 9 days agoRepo

Radar

DevOps & Cloud

2.4k

Built-in MCP server for the open-source Kubernetes UI — lets AI assistants query and operate your cluster.

Unverified

HTTP (remote)

No auth

25 tools

Updated 1 day agoRepo

Compare kubefwd with:

vs GitHub MCP Server vs AWS API MCP Server vs Radar vs Grafana MCP Server