K8s MCP Server

What is K8s MCP Server?

K8s MCP Server is an AI-friendly Kubernetes access tool that supports enhanced port‑forward management, headless services, and kubectl‑inspired output formats. It is designed for AI agents and developers who need efficient, context‑aware interaction with Kubernetes clusters.

How to use K8s MCP Server?

Install dependencies with pip install -e ., set environment variables such as KUBECONFIG_URLS and PORT_FORWARD_CONFIG_URL, then run python main.py. The server provides MCP tools for reading, modifying, and discovering resources, along with port‑forward session management.

Key features of K8s MCP Server

• kubectl‑inspired output formats (table, wide, json, yaml, custom‑columns, jsonpath)
• Natural‑language resource kind discovery for CRDs and built‑in resources
• URL‑based port‑forward configuration via local files or GitHub Gists
• Headless service support with direct pod targeting via label selectors
• Token‑efficient AI‑optimized output and multi‑format config files (YAML, JSON, TOML)
• In‑memory port‑forward session tracking with list and teardown capabilities

Use cases of K8s MCP Server

• AI agents perform cluster overview, application debugging, and safe deployment updates
• Automated port‑forward setup for AI workflows (e.g., connecting to a Druid service in development)
• Resource cleanup and security audits using read‑only or modify tools
• Performance troubleshooting and disaster recovery with structured tool workflows
• Multi‑cluster resource discovery and exploration without manual kubectl commands

FAQ from K8s MCP Server

What Kubernetes resources can I list or query?

You can list pods, services, deployments, nodes, events, and any custom resource kind discovered via discover_resource_kinds. The server supports plural, singular, and abbreviated resource names (e.g., pods, pod, po), and case‑insensitive input.

How does the port‑forward configuration work?

Port‑forward targets are defined in a YAML/JSON/TOML file, referenced by PORT_FORWARD_CONFIG_URL. Each target specifies a cluster alias, namespace, label selectors, local port, and remote port. The AI agent can then use connect_to_service_targets to set up the forward.

Are the tools safe for autonomous AI use?

Tools are classified into three safety levels: [READ-ONLY] (safe for autonomous use, e.g., list_resources, get_logs), [MODIFIES STATE] (require user approval, e.g., apply_manifest, connect_to_service_targets), and [DANGEROUS] (require explicit confirmation, e.g., delete_resource, execute_in_pod).

Does K8s MCP Server support headless services?

Yes. For headless services, the server selects the first ready pod using label selectors, mimicking kubectl port-forward behavior. This is configured in the port‑forward config file under each service target.

What transport or authentication does the server use?

The server uses the MCP stdio transport and relies on existing Kubernetes authentication (kubeconfig) configured via the KUBECONFIG_URLS environment variable. It does not implement additional authentication layers.