k8s-mcp-server

Implements Anthropic's Model Context Protocol (MCP) as a server that translates Claude's natural language requests into structured tool calls for kubectl, helm, istioctl, and argocd. Uses a request-response pattern where Claude sends MCP messages that are parsed, validated against security policies, and dispatched to the appropriate CLI tool handler. The system maintains bidirectional communication with Claude Desktop via stdio, enabling real-time command execution and result streaming.

Provides a single MCP tool registry that abstracts kubectl, helm, istioctl, and argocd CLI tools, allowing Claude to invoke any tool through a consistent schema-based interface. Each tool is registered with its own command templates, argument validators, and execution handlers. The system dynamically generates MCP tool definitions from tool configurations, enabling Claude to discover available operations without hardcoding tool knowledge.

Provides prompt templates that are sent to Claude along with tool definitions, giving Claude context about how to use the Kubernetes tools effectively. Templates include instructions for common operations (deploying applications, troubleshooting pods, managing helm releases), best practices for Kubernetes operations, and warnings about dangerous commands. Templates are customizable and can be extended with organization-specific guidance.

Implements a multi-layer security architecture that validates commands before execution using configurable security policies. The system checks command syntax against tool-specific schemas, enforces namespace restrictions, validates resource types, and applies custom policy rules defined in configuration files. Uses a defense-in-depth approach with container isolation, read-only credential mounts, and audit logging of all executed commands.

Manages credentials for AWS EKS, Google GKE, and Azure AKS by mounting cloud provider configuration files as read-only volumes into the container. The system supports kubeconfig files, AWS credentials, GCP service accounts, and Azure credentials, enabling the container to authenticate to multiple cloud providers without embedding secrets in the image. Credentials are never logged or exposed in command output.

Executes validated Kubernetes CLI commands in a subprocess and captures stdout/stderr with structured parsing. The system detects JSON output (when tools are invoked with --output=json flags) and returns parsed JSON objects, or returns raw text output for human-readable formats. Includes timeout handling, exit code capture, and error message extraction to provide Claude with actionable feedback.

Packages the MCP server as a Docker container (ghcr.io/alexei-led/k8s-mcp-server) with all Kubernetes CLI tools pre-installed and configured. The container runs as an isolated process with read-only root filesystem, no network access to the host, and credential files mounted as read-only volumes. Supports deployment via Claude Desktop, Docker Compose, or standalone container orchestration.

Integrates with Claude Desktop by configuring the MCP server to communicate via stdio (standard input/output) rather than TCP sockets. Claude Desktop launches the container as a subprocess and communicates with it using JSON-RPC 2.0 messages over stdin/stdout. The integration is configured via Claude Desktop's configuration file (claude_desktop_config.json), which specifies the Docker image, volume mounts, and environment variables.

Dynamically generates MCP tool definitions (JSON schemas) from tool configurations, allowing Claude to discover available Kubernetes operations without hardcoding tool knowledge. Each tool (kubectl, helm, istioctl, argocd) has a configuration that defines its command templates, required arguments, optional flags, and output format. The system validates tool definitions against the MCP schema specification and exposes them to Claude via the MCP tools/list endpoint.

Captures and formats error messages from failed Kubernetes commands, providing Claude with actionable diagnostic information. When a command fails, the system extracts the exit code, stderr output, and tool-specific error patterns to generate a structured error response. Includes timeout detection, permission errors, resource not found errors, and connection failures with appropriate error messages.

Manages configuration for all tools and security policies through YAML configuration files that are loaded at server startup. Configuration includes tool command templates, argument validators, security policies (namespace restrictions, resource type filters), and execution settings (timeouts, retry logic). The system supports environment variable substitution in configuration files, enabling dynamic configuration based on deployment context.