Kubernetes MCP Server

A Kubernetes Model Context Protocol (MCP) server that provides tools for interacting with Kubernetes clusters through a standardized interface.

Features

• API Resource Discovery: Get all available API resources in your Kubernetes cluster.
• Resource Listing: List resources of any type with optional namespace and label filtering.
• Resource Details: Get detailed information about specific Kubernetes resources.
• Resource Description: Get comprehensive descriptions of Kubernetes resources, similar to kubectl describe.
• Pod Logs: Retrieve logs from specific pods (optionally from a specific container, or all containers if unspecified).
• Node Metrics: Get resource usage metrics for specific nodes.
• Pod Metrics: Get CPU and Memory metrics for specific pods.
• Event Listing: List events within a namespace or for a specific resource.
• Resource Creation/Updating: Create new Kubernetes resources or update existing ones from a YAML or JSON manifest.
• Standardized Interface: Uses the MCP protocol for consistent tool interaction.
• Flexible Configuration: Supports different Kubernetes contexts and resource scopes.
• Multiple Modes: Run in stdio mode for CLI tools or sse mode for web applications.
• Security: Runs as non-root user in Docker containers for enhanced security.

Prerequisites

• Go 1.23 or later
• Access to a Kubernetes cluster
• kubectl configured with appropriate cluster access

Installation

1. Clone the repository:

   git clone https://github.com/reza-gholizade/k8s-mcp-server.git
   cd k8s-mcp-server
   

2. Install dependencies:

   go mod download
   

3. Build the server:

   go build -o k8s-mcp-server main.go
   

Usage

Starting the Server

The server can run in two modes, configurable via command-line flags or environment variables.

Stdio Mode (for CLI integrations)

This mode uses standard input/output for communication.

./k8s-mcp-server --mode stdio

Or using environment variables:

SERVER_MODE=stdio ./k8s-mcp-server

SSE Mode (for web applications)

This mode starts an HTTP server with Server-Sent Events support.

Default (port 8080):

./k8s-mcp-server --mode sse

Specify a port:

./k8s-mcp-server --mode sse --port 9090

Or using environment variables:

SERVER_MODE=sse SERVER_PORT=9090 ./k8s-mcp-server

If no mode is specified, it defaults to SSE on port 8080.

Using the Docker Image

You can also run the server using the pre-built Docker image from Docker Hub.

1. Pull the image:

   docker pull ginnux/k8s-mcp-server:latest
   

   You can replace latest with a specific version tag (e.g., 1.0.0).

2. Run the container:

   • SSE Mode (default behavior of the image):

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

     This maps port 8080 of the container to port 8080 on your host and mounts your Kubernetes config read-only to the non-root user's home directory. The server will be available at http://localhost:8080. The image defaults to sse mode on port 8080.

   • Stdio Mode:

     docker run -i --rm -v ~/.kube/config:/home/appuser/.kube/config:ro ginnux/k8s-mcp-server:latest --mode stdio
     

     The -i flag is important for interactive stdio communication. --rm cleans up the container after exit.

   • Custom Port for SSE Mode:

     docker run -p 9090:9090 -v ~/.kube/config:/home/appuser/.kube/config:ro ginnux/k8s-mcp-server:latest --mode sse --port 9090
     

   • Alternative: Mount entire .kube directory:

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

Using with Docker Compose

Creat

... View full README on GitHub