A Kubernetes management MCP (Model Context Protocol) server that provides interfaces for getting information about Kubernetes clusters, performing operations, monitoring status, and analyzing resources.

• Cluster Information: Get detailed information about Kubernetes resources (pods, deployments, services, etc.)
• Cluster Operations: Perform operations on Kubernetes resources (create, update, delete, scale, etc.)
• Monitoring: Monitor the status of Kubernetes clusters and resources
• Analysis: Analyze Kubernetes resources and provide recommendations
• Prompts: Includes prompts for common Kubernetes analysis tasks

git clone https://github.com/yourusername/mcp-k8s-server.git
cd mcp-k8s-server
pip install -e .

pip install mcp-k8s-server

# Run with default settings
mcp-k8s-server

# Specify transport type
mcp-k8s-server --transport sse

# Specify port for SSE transport
mcp-k8s-server --port 8000

# Specify config file
mcp-k8s-server --config /path/to/config.yaml

The Dockerfile uses the command and args pattern to run the server:

CMD ["python", "-m", "mcp_k8s_server.main", \
     "--transport", "sse", \
     "--port", "8000", \
     "--host", "0.0.0.0", \
     "--config", "/etc/rancher/rke2/rke2.yaml", \
     "--debug"]

To build and run the Docker container:

# Build the Docker image
docker build -t mcp-k8s-server .

# Run the Docker container
docker run -p 8000:8000 -v ~/.kube:/home/mcp/.kube mcp-k8s-server

Alternatively, you can use the provided script:

# Make the script executable
chmod +x docker-run.sh

# Run the script
./docker-run.sh

This script builds the Docker image and runs the container with the necessary volume mounts.

# Apply the Kubernetes manifests
kubectl apply -f k8s/

When deploying to Kubernetes, the server will automatically use the in-cluster configuration. The Kubernetes manifests in the k8s/ directory are set up to:

1. Create a ServiceAccount with appropriate permissions
2. Mount the service account token and certificate
3. Configure the server with command-line arguments

You can customize the deployment by editing the manifests:

# k8s/deployment.yaml (example)
apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-k8s-server
  # ...
spec:
  # ...
  template:
    # ...
    spec:
      serviceAccountName: mcp-k8s-server  # Uses the ServiceAccount defined in rbac.yaml
      containers:
      - name: mcp-k8s-server
        # ...
        command:
        - python
        - -m
        - mcp_k8s_server.main
        args:
        - --transport
        - sse
        - --port
        - "8000"
        - --host
        - "0.0.0.0"
        - --config
        - "/app/config/config.yaml"
        - --debug

This approach uses the command and args pattern to configure the server, which is a common pattern in Kubernetes. The command specifies the executable to run, and the args specify the command-line arguments to pass to the executable.

The KUBERNETES_SERVICE_HOST and KUBERNETES_SERVICE_PORT environment variables are automatically set by Kubernetes when the pod is created, so you don't need to specify them in your deployment manifest.

The server can be configured using a YAML configuration file, environment variables, or command-line arguments.

When running inside a Kubernetes cluster, the server automatically uses the in-cluster configuration. This relies on the following:

1. Environment variables:

   • KUBERNETES_SERVICE_HOST: Set by Kubernetes to the IP address of the Kubernetes API server
   • KUBERNETES_SERVICE_PORT: Set by Kubernetes to the port of the Kubernetes API server

2. Service account token and certificate:

   • /var/run/secrets/kubernetes.io/serviceaccount/token: Service account token
   • /var/run/secrets/kubernetes.io/serviceaccount/ca.crt: CA certificate

These are automatically set by Kubernetes when running in a pod. If you're running the server outside a Kubernetes cluster but want to test the in-cluster configuration, you would need to manually set these environment variables and create the token and certificate files.

When running outside a cluster, the server falls back to using the kubeconfig file.

If you want to test the in-cluster configuration locally (outside a Kubernetes cluster), you can manually set up the required environment variables and files:

1. Set the environment variables:

   export KUBERNETES_SERVICE_HOST=<kubernetes-api-server-ip>
   export KUBERNETES_SERVICE_PORT=<kubernetes-api-server-port>

   You can get these values by running:

   kubectl cluster-info

2. Create the service account token and certificate directories:

   mkdir -p /var/run/secrets/kubernetes.io/serviceaccount/

3. Copy your Kubernetes certificate and create a token:

   # Copy the CA certificate
   kubectl config view --raw -o jsonpath='{.clusters[0].cluster.certificate-authority-data}' | base64 -d > /var/run/secrets/kubernetes.io/serviceaccount/ca.crt
   
   # Create a token file (you can use a service account token or generate a temporary one)
   echo "your-service-account-token" > /var/run/secrets/kubernetes.io/serviceaccount/token

Note that this approach requires root privileges to create files in /var/run/secrets/. Alternatively, you can modify the code to use different paths for testing purposes.

# config.yaml
server:
  name: mcp-k8s-server
  transport: both  # stdio, sse, or both
  port: 8000
  host: 0.0.0.0

kubernetes:
  config_path: ~/.kube/config
  context: default
  namespace: default

The server provides access to Kubernetes resources through the Model Context Protocol (MCP). Resources are identified by URI patterns following the k8s:// protocol.

Resources are organized in a hierarchical structure:

• k8s://resources - List of all available Kubernetes resources
• k8s://namespaces - List of all Kubernetes namespaces
• k8s:///{namespace} - Overview of all resources in a namespace

• k8s://{namespace}/{resource_type} - List resources of a specific type in a namespace

  • Example: k8s://default/pods - All pods in the 'default' namespace

• k8s://{namespace}/{resource_type}/{name} - Get a specific namespaced resource

  • Example: k8s://default/deployments/nginx - The 'nginx' deployment in the 'default' namespace

Supported resource types:

• pods
• deployments
• services
• persistentvolumeclaims
• events

• k8s:///{resource_type} - List cluster-scoped resources of a specific type

  • Example: k8s:///nodes - All nodes in the cluster

• k8s:///{resource_type}/{name} - Get a specific cluster-scoped resource

  • Example: k8s:///nodes/worker-1 - The 'worker-1' node

Supported resource types:

• nodes
• persistentvolumes
• namespaces

The server provides the following MCP tools:

• get_resources: Get a list of resources of a specific type
• get_resource: Get detailed information about a specific resource
• get_resource_status: Get the status of a specific resource
• get_resource_events: Get events related to a specific resource
• get_resource_logs: Get logs for a specific resource

• create_resource: Create a new resource
• update_resource: Update an existing resource
• delete_resource: Delete a resource
• scale_deployment: Scale a deployment
• restart_deployment: Restart a deployment
• execute_command: Execute a command in a pod

• get_cluster_status: Get the overall status of the cluster
• get_node_status: Get the status of cluster nodes
• get_resource_metrics: Get metrics for a specific resource
• get_cluster_metrics: Get metrics for the entire cluster
• check_cluster_health: Perform a comprehensive health check of the cluster and get a detailed summary

MIT