MCP Kubernetes Server

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

Features

• 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

Examples

Ex.1

Ex.2

Ex.3

Installation

From Source

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

Using pip

pip install mcp-k8s-server

Usage

Running Directly

# 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

Using Docker

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.

Deploying to Kubernetes

# 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.

Configuration

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

In-Cluster Configuration

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.

Testing In-Cluster Configuration Locally

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.

Configuration File

# 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

MCP Resources

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

Resource URI Patterns

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

Namespaced Resources

• 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

Cluster-Scoped Resources

• 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

MCP Tools

The server provides the following MCP tools:

Resource Information

• 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

Resource Operations

• 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

Monitoring

• 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

License

MIT