kubectl-mcp-server for Windsurf: Setup & Config

What you can do with kubectl-mcp-server in Windsurf

A broad Kubernetes operations surface for assistant-led diagnostics, Helm work, and resource analysis.

• Investigate a crashed pod using logs and events.
• Create, scale, or roll back deployments.
• Identify idle workloads and oversized resource requests.

Before you start: kubectl-mcp-server in Windsurf

• Node.js 14+ for the npx method
• kubectl installed and configured
• Access to a Kubernetes cluster

The README recommends this npx launch for MCP clients. Python installation instead requires Python 3.9+. Optional UI features have a separate dependency extra. Docker can use stdio or --transport sse. The tool list here is a selection of explicitly named README operations, not the entire catalog.

kubectl-mcp-server Windsurf configuration

1. Choose Windsurf configuration scope

   For kubectl-mcp-server, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

2. Add kubectl-mcp-server to Windsurf

   Use the kubectl-mcp-server entry below in mcpServers. Keep kubectl-mcp-server's documented stdio connection fields and your other Windsurf entries.

3. Check kubectl-mcp-server in Windsurf

   kubectl-mcp-server: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

{
  "mcpServers": {
    "kubectl-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "kubectl-mcp-server"
      ],
      "env": {}
    }
  }
}

kubectl-mcp-server tools available to Windsurf

kubectl-mcp-server's stored tool list documents 23 tools; compare it with Windsurf's connected tool list, because the stored list is not a live check.

get_pods

After refreshing kubectl-mcp-server in Windsurf settings, check Cascade's tool list for get_pods.

List pods for a Kubernetes namespace.

get_logs

After refreshing kubectl-mcp-server in Windsurf settings, check Cascade's tool list for get_logs.

Retrieve logs from a pod.

get_pod_events

After refreshing kubectl-mcp-server in Windsurf settings, check Cascade's tool list for get_pod_events.

diagnose_pod_crash

After refreshing kubectl-mcp-server in Windsurf settings, check Cascade's tool list for diagnose_pod_crash.

create_deployment

After refreshing kubectl-mcp-server in Windsurf settings, check Cascade's tool list for create_deployment.

scale_deployment

After refreshing kubectl-mcp-server in Windsurf settings, check Cascade's tool list for scale_deployment.

kubectl_rollout

After refreshing kubectl-mcp-server in Windsurf settings, check Cascade's tool list for kubectl_rollout.

diagnose_network_connectivity

After refreshing kubectl-mcp-server in Windsurf settings, check Cascade's tool list for diagnose_network_connectivity.

Investigate service and workload connectivity problems.

check_dns_resolution

After refreshing kubectl-mcp-server in Windsurf settings, check Cascade's tool list for check_dns_resolution.

Check DNS behavior relevant to cluster connectivity.

audit_rbac_permissions

After refreshing kubectl-mcp-server in Windsurf settings, check Cascade's tool list for audit_rbac_permissions.

Analyze Kubernetes role and permission configuration.

check_secrets_security

After refreshing kubectl-mcp-server in Windsurf settings, check Cascade's tool list for check_secrets_security.

Inspect secrets for security concerns.

helm_list

After refreshing kubectl-mcp-server in Windsurf settings, check Cascade's tool list for helm_list.

List Helm releases in the cluster.

install_helm_chart

After refreshing kubectl-mcp-server in Windsurf settings, check Cascade's tool list for install_helm_chart.

helm_rollback

After refreshing kubectl-mcp-server in Windsurf settings, check Cascade's tool list for helm_rollback.

get_current_context

After refreshing kubectl-mcp-server in Windsurf settings, check Cascade's tool list for get_current_context.

switch_context

After refreshing kubectl-mcp-server in Windsurf settings, check Cascade's tool list for switch_context.

list_contexts

After refreshing kubectl-mcp-server in Windsurf settings, check Cascade's tool list for list_contexts.

get_resource_recommendations

After refreshing kubectl-mcp-server in Windsurf settings, check Cascade's tool list for get_resource_recommendations.

get_idle_resources

After refreshing kubectl-mcp-server in Windsurf settings, check Cascade's tool list for get_idle_resources.

Find resources that appear idle.

get_cost_analysis

After refreshing kubectl-mcp-server in Windsurf settings, check Cascade's tool list for get_cost_analysis.

Analyze cluster resource costs.

get_overprovisioned_resources

After refreshing kubectl-mcp-server in Windsurf settings, check Cascade's tool list for get_overprovisioned_resources.

Identify workloads with excessive resource allocation.

delete_resource

After refreshing kubectl-mcp-server in Windsurf settings, check Cascade's tool list for delete_resource.

Delete a selected Kubernetes resource.

show_cluster_overview_ui

After refreshing kubectl-mcp-server in Windsurf settings, check Cascade's tool list for show_cluster_overview_ui.

Present an optional interactive cluster overview.

kubectl-mcp-server: full stored tool descriptions

Troubleshooting kubectl-mcp-server in Windsurf

• Check npx kubectl-mcp-server (Node.js/npm) on the machine running Windsurf's MCP integration for kubectl-mcp-server; refresh MCP and inspect Cascade's tools.
• kubectl-mcp-server uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Needs kubectl configuration and working cluster access.
• Known limitation: The tool catalog includes destructive resource operations.
• Known limitation: Interactive dashboards require optional dependencies.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions