Kube Context Interactor Agent (k8s-mcp-server Rewrite)

This agent serves as a highly configurable Model Context Protocol (MCP) endpoint, offering robust, standardized tooling for manipulating and querying Kubernetes environments. It prioritizes operational safety by default, supporting various communication transports tailored for CLI and web integration.

Core Capabilities

This utility provides comprehensive control over K8s objects:

• Discovery & Inquiry: Enumerating available API schemas, fetching lists of resources (filterable by namespace/labels), and retrieving granular details or descriptive summaries (analogous to kubectl describe).
• State Retrieval: Accessing live container outputs (pod logs), fetching performance utilization data (nodeMetrics, podMetrics), and tracking cluster events.
• Manipulation: Executing imperative operations such as resource provisioning, modification via manifests (JSON/YAML), and resource deprecation (deleteResource).
• Advanced Operations: Includes utility functions like triggering configuration updates via rolloutRestart for Deployments, DaemonSets, etc.

Transport Modes & Configuration

The agent supports flexible deployment strategies:

1. stdio: Ideal for piping through standard command-line interfaces or integrating with local shell tools.
2. sse (Server-Sent Events): Enables persistent, one-way real-time updates over HTTP.
3. streamable-http: A bi-directional streaming HTTP transport conforming strictly to the MCP specification.

Deployment defaults to sse on port 8080 if no mode is specified.

Safety First: Read-Only Operation

By enabling the --readonly flag, all mutation capabilities (resource creation, updates, deletion) are immediately suppressed, confining the agent to monitoring and data retrieval functions.

Tool Scoping

Granular control over exposed toolsets is possible:

• --no-k8s: Deactivates all native Kubernetes interaction tools.
• --no-helm: Deactivates all integrated Helm management utilities (installation, upgrades, rollbacks, etc.).

Attempting to disable both scopes results in an immediate exit with an error.

Prerequisites & Building

Requires Go version 1.23 or newer. Building involves standard Go tooling:

bash git clone [REPO_URL] cd k8s-mcp-server go mod download go build -o k8s-mcp-server main.go

Execution Examples

Starting in Streamable HTTP Mode:

bash ./k8s-mcp-server --mode streamable-http --port 9999

Starting in Read-Only Stdio Mode:

bash SERVER_MODE=stdio SERVER_READONLY=true ./k8s-mcp-server

Docker Deployment

Pre-built images are available on Docker Hub (ginnux/k8s-mcp-server:latest). The container is secured by default, running as a non-root user (appuser UID 1001) and expecting cluster credentials to be mounted read-only into /home/appuser/.kube/config.

Standard SSE Docker Run:

bash docker run -p 8080:8080 -v ~/.kube/config:/home/appuser/.kube/config:ro ginnux/k8s-mcp-server:latest

Integrated Tool Specifications (JSON-RPC Methods)

Interaction occurs via the MCP standard JSON-RPC tools/call method. Below are key operations:

Tool Name	Primary Function	Key Arguments	Write Operation?
getAPIResources	Inventory of available K8s API groups/versions.	includeNamespaceScoped, includeClusterScoped	No
listResources	Fetch multiple instances of a resource type.	Kind, namespace, labelSelector	No
getResource	Fetch a single object by name/kind/namespace.	kind, name, namespace	No
describeResource	Yields detailed observational summary.	Kind, name, namespace	No
getPodsLogs	Stream container output logs.	Name, namespace, containerName	No
getNodeMetrics	Retrieve resource usage statistics for nodes.	Name	No
getPodMetrics	Retrieve CPU/Memory consumption for pods.	namespace, podName	No
getEvents	Capture cluster or resource-specific events.	namespace, resourceName	No
createOrUpdateResource	Provision or modify resources using JSON payload.	manifest, namespace	Yes
createOrUpdateResourceYAML	Provision or modify resources using YAML payload.	manifest, namespace	Yes
deleteResource	Terminate a specified object.	kind, name, namespace	Yes
rolloutRestart	Force a rolling update annotation on stateful resources.	kind, name, namespace	Yes
getIngresses	Fetch ingress definitions, optionally filtered by host.	host	No

Helm Operations (If --no-helm is not set)

• helmInstall, helmUpgrade, helmRollback, helmUninstall: Standard Helm lifecycle management.
• helmList, helmGet, helmHistory: Release status retrieval.

VS Code Connectivity

This agent is optimized for seamless integration with the Model Context Protocol (MCP) VS Code Extension. Configuration involves setting the server command to the binary path (e.g., k8s-mcp-server), specifying the transport mode (typically stdio), and correctly mapping the KUBECONFIG environment variable within VS Code's mcp.mcpServers settings object.

Licensing and Support

Licensed under the MIT License. Direct inquiries or contributions can be sent to the maintainer via gholizade.net@gmail.com. Contributions are detailed in CONTRIBUTING.md.