Kube Compare Mcp

kube-compare-mcp

MCP server for kube-compare - enables AI assistants to compare Kubernetes cluster configurations against reference templates.

Table of Contents

• [Overview](#overview)
• [Architecture](#architecture)
• [Quick Start](#quick-start)
• [Installation](#installation)
• [Running the Server](#running-the-server)
• [Deployment](#deployment)
• [MCP Tools Reference](#mcp-tools-reference)
• [kubecompareclusterdiff](#kubecompareclusterdiff)
• [kubecompareresolverds](#kubecompareresolverds)
• [kubecomparevalidaterds](#kubecomparevalidaterds)
• [baremetalbiosdiff](#baremetalbiosdiff)
• [RDS Support](#rds-reference-design-specification-support)
• [BIOS Reference Configurations](#bios-reference-configurations)
• [Connecting to Remote Clusters](#connecting-to-remote-clusters)
• [Reference Configuration Formats](#reference-configuration-formats)
• [Output Formats](#output-formats)
• [Configuration](#configuration)
• [Development](#development)
• [Related Projects](#related-projects)
• [License](#license)

Overview

This project provides a Model Context Protocol (MCP) server for Kubernetes / OpenShift cluster compliance checking. It allows AI assistants like Claude, Cursor, OpenShift Lightspeed (OLS), and other MCP-compatible clients to:

• Compare live Kubernetes cluster configurations against reference templates
• Detect configuration drift from known-good baselines
• Generate structured comparison reports in JSON, YAML, or JUnit formats
• Automatically discover and use Red Hat Telco Reference Design Specifications (RDS)
• Compare bare metal host BIOS settings against reference configurations for ZTP-provisioned clusters

Note: This server is designed for remote deployment (e.g., in a Kubernetes cluster). Reference configurations must be provided via HTTP/HTTPS URLs or OCI container image references - local filesystem paths are not supported.

Architecture

flowchart TB
    subgraph clients [MCP Clients]
        Cursor[Cursor IDE]
        Claude[Claude Desktop]
        OLS[OpenShift Lightspeed]
    end

    subgraph server [kube-compare-mcp Server]
        Transport[Transport Layerstdio / http]
        Tools[MCP Tools]
        Diff[kube_compare_cluster_diff]
        ResolveRDS[kube_compare_resolve_rds]
        ValidateRDS[kube_compare_validate_rds]
        BIOSDiff[baremetal_bios_diff]
    end

    subgraph external [External Resources]
        K8sCluster[Kubernetes Cluster]
        Registry[Container Registryregistry.redhat.io]
        HTTPRef[HTTP References]
    end

    Cursor --> Transport
    Claude --> Transport
    OLS --> Transport
    Transport --> Tools
    Tools --> Diff
    Tools --> ResolveRDS
    Tools --> ValidateRDS
    Tools --> BIOSDiff
    Diff --> K8sCluster
    Diff --> Registry
    Diff --> HTTPRef
    ResolveRDS --> K8sCluster
    ResolveRDS --> Registry
    ValidateRDS --> Diff
    ValidateRDS --> ResolveRDS
    BIOSDiff --> K8sCluster

Quick Start

# Build the server
git clone https://github.com/sakhoury/kube-compare-mcp.git
cd kube-compare-mcp
make build

# Run locally with stdio transport (for local MCP clients)
./bin/kube-compare-mcp

# Or run with HTTP transport for network access
./bin/kube-compare-mcp --transport=http --port=8080

Installation

Build from source

git clone https://github.com/sakhoury/kube-compare-mcp.git
cd kube-compare-mcp
make build

The binary will be available at bin/kube-compare-mcp.

Install to system path

sudo make install

Build for specific platforms

# macOS Apple Silicon
make build-darwin-arm64

# macOS Intel
make build-darwin-amd64

# Linux x86_64 (for containers/servers)
make build-linux-amd64

# All platforms
make build-all

Running the Server

CLI Options

| Flag | Description | Default | |------|-------------|---------| | --transport | Transport mode: stdio or http | stdio | | --port | Port to listen on (for http transport) | 8080 | | --log-level | Log level: debug, info, warn, error | info | | --log-format | Log format: text, json | text | | --version | Show version information | - |

Transport Modes

stdio (default)

For local MCP clients like Cursor and Claude Desktop running on the same machine:

./bin/kube-compare-mcp --transport=stdio

HTTP (Streamable HTTP)

For network access and MCP client integration (Cursor, Claude Desktop, OpenShift Lightspeed):

./bin/kube-compare-mcp --transport=http --port=8080

Endpoints:

• POST /mcp - MCP endpoint
• GET /health - Health check endpoint

Deployment

Kubernetes / OpenShift

The recommended deployment is as a service in your Kubernetes cluster. This allows the MCP server to use in-cluster authentication and directly access the cluster API.

Deploy using the provided Kustomize manifests:

kubectl apply -k deploy/

This creates:

• A Deployment running the MCP server with HTTP transport
• A Service exposing the MCP server
• A Route (OpenShift) for external access
• RBAC resources for cluster read access

Quick Deploy (Build, Push, Deploy, and Configure)

Build the container image, push to registry, deploy to OpenShift, and configure registry credentials in one command:

make docker-build docker-push deploy setup-registry-credentials IMG=quay.io/myuser/kube-compare-mcp:latest

Registry Credentials (Required for RDS)

If using the RDS tools (kube_compare_resolve_rds or kube_compare_validate_rds), you need to provide credentials for registry.redhat.io.

On OpenShift (recommended): Use the Makefile target to copy the existing cluster pull-secret:

make setup-registry-credentials

Alternatively, create credentials from username/password:

kubectl create secret docker-registry registry-credentials \
  --docker-server=registry.redhat.io \
  --docker-username= \
  --docker-password= \
  -n kube-compare-mcp

Or use a local pull-secret file:

kubectl create secret generic registry-credentials \
  --from-file=.dockerconfigjson=/path/to/pull-secret.json \
  --type=kubernetes.io/dockerconfigjson \
  -n kube-compare-mcp

OpenShift Lightspeed (OLS) Integration

To configure OpenShift Lightspeed to use this MCP server, add the following to your OLSConfig:

spec:
  featureGates:
    - MCPServer
  mcpServers:
    - name: kube-compare-mcp
      streamableHTTP:
        url: http://kube-compare-mcp.kube-compare-mcp.svc.cluster.local:8080/mcp
        timeout: 60
        sseReadTimeout: 0
        enableSSE: false

Configuration for MCP Clients

Configure your MCP client to connect to the server's endpoint:

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "kube-compare": {
      "url": "https://kube-compare-mcp-route.apps.your-cluster.example.com/mcp"
    }
  }
}

Claude Desktop:

{
  "mcpServers": {
    "kube-compare": {
      "url": "https://kube-compare-mcp-route.apps.your-cluster.example.com/mcp"
    }
  }
}

Local stdio mode (Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "kube-compare": {
      "command": "/path/to/kube-compare-mcp",
      "args": ["--transport=stdio"]
    }
  }
}

MCP Tools Reference

The server exposes four MCP tools:

kubecomparecluster_diff

Detect configuration drift between a Kubernetes/OpenShift cluster and a reference design.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | reference | string | Yes | URL to the reference configuration metadata.yaml file. Supports HTTP/HTTPS URLs or container image references (container://image:tag:/path/to/metadata.yaml). | | output_format | string | No | Output format: json, yaml, or junit. Default: json. | | all_resources | boolean | No | Compare all resources of types mentioned in the reference. Default: false. | | kubeconfig | string | No | Kubeconfig content for connecting to a remote cluster (raw YAML or base64-encoded, auto-detected). If not provided, uses in-cluster config or KUBECONFIG env. | | context | string | No | Kubernetes context name to use from the provided kubeconfig. Only applicable when kubeconfig is provided. |

Example prompts:

Compare my Kubernetes cluster against the reference configuration at https://example.com/telco-core/metadata.yaml

Run kube-compare on my cluster using reference container://quay.io/openshift-kni/telco-core-rds-rhel9:v4.18:/metadata.yaml

kubecompareresolve_rds

Get the correct Red Hat Telco RDS container reference for a cluster's OpenShift version.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | rds_type | string | Yes | RDS type: core for Telco Core RDS, ran for Telco RAN DU RDS, or hub for Telco Hub RDS (requires OCP 4.19+). | | ocp_version | string | No | Explicit OpenShift version (e.g., 4.18, 4.20.0). If not provided, auto-detects from cluster. | | kubeconfig | string | No | Kubeconfig content (raw YAML or base64-encoded, auto-detected). If not provided and ocp_version is not set, uses in-cluster config. | | context | string | No | Kubernetes context name to use from the provided kubeconfig. |

Response:

{
  "cluster_version": "4.18.0",
  "rhel_version": "rhel9",
  "rds_type": "core",
  "reference": "container://registry.redhat.io/openshift4/openshift-telco-core-rds-rhel9:v4.18:/usr/share/telco-core-rds/configuration/reference-crs-kube-compare/metadata.yaml",
  "available_versions": ["v4.16", "v4.17", "v4.18", "v4.19"],
  "validated": true
}

Example prompts:

Find the Telco Core RDS reference for my OpenShift 4.18 cluster

What RDS reference should I use for a RAN deployment on OpenShift 4.20?

Find the Telco Hub RDS reference for my OpenShift 4.19 cluster

kubecomparevalidate_rds

Validate an OpenShift cluster's compliance with Red Hat Telco RDS. This is the recommended tool for RDS validation.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | rds_type | string | Yes | RDS type: core for Telco Core RDS, ran for Telco RAN DU RDS, or hub for Telco Hub RDS (requires OCP 4.19+). | | output_format | string | No | Output format: json, yaml, or junit. Default: json. | | all_resources | boolean | No | Compare all resources of types mentioned in the reference. Default: false. | | kubeconfig | string | No | Kubeconfig content (raw YAML or base64-encoded, auto-detected). If not provided, uses in-cluster config. | | context | string | No | Kubernetes context name to use from the provided kubeconfig. |

Response:

{
  "rds_reference": {
    "cluster_version": "4.18.0",
    "rhel_version": "rhel9",
    "rds_type": "core",
    "reference": "container://...",
    "available_versions": ["v4.16", "v4.17", "v4.18"],
    "validated": true
  },
  "comparison": {
    "Summary": { ... },
    "Diffs": [ ... ]
  }
}

Example prompts:

Compare my cluster against the Telco Core RDS

Check if my OpenShift cluster is compliant with the Telco RAN DU reference design

Validate my hub cluster against the Telco Hub RDS for OpenShift 4.19

baremetalbiosdiff

Compare BIOS versions and settings of bare metal hosts against reference configurations. Targets ZTP-provisioned clusters managed via ACM hub.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | namespace | string | Yes | Namespace on the hub cluster containing BareMetalHost resources to compare. | | host_name | string | No | Specific host to compare. Omit to compare all hosts in the namespace. | | reference_source | string | No | Namespace containing BIOS reference ConfigMaps. Default: reference-configs. | | reference_override | string | No | Explicit ConfigMap name to use, bypassing auto-matching by server model. | | output_format | string | No | Output format: json or yaml. Default: json. | | kubeconfig | string | No | Kubeconfig content for the ACM hub cluster (raw YAML or base64-encoded, auto-detected). If not provided, uses in-cluster config. | | context | string | No | Kubernetes context name to use from the provided kubeconfig. Only applicable when kubeconfig is provided. |

Response:

{
  "Namespace": "my-cluster",
  "Hosts": [
    {
      "Name": "worker-0",
      "Namespace": "my-cluster",
      "Role": "worker",
      "ServerModel": {
        "Manufacturer": "Dell Inc.",
        "ProductName": "XR8620t"
      },
      "Reference": "bios-ref-dell-xr8620t-worker",
      "ReferenceSource": "mcp-server-cluster",
      "BIOSVersion": {
        "Expected": "2.19.1",
        "Actual": "2.18.0",
        "Match": false
      },
      "SettingsDiff": [
        {
          "Setting": "SriovGlobalEnable",
          "Expected": "Enabled",
          "Actual": "Disabled"
        }
      ],
      "Compliant": false
    }
  ],
  "Summary": {
    "TotalHosts": 1,
    "CompliantHosts": 0,
    "NumDiffHosts": 1,
    "ErrorHosts": 0
  }
}

Example prompts:

Compare the BIOS settings of all hosts in namespace my-cluster against reference configurations

Check if host worker-0 in namespace my-cluster has compliant BIOS settings

Validate BIOS configuration for all bare metal hosts in the spoke-cluster-1 namespace

RDS (Reference Design Specification) Support

This server includes specialized support for Red Hat's Telco Reference Design Specifications:

Telco Core RDS (core)

For telco core network functions on OpenShift.

• Image: registry.redhat.io/openshift4/openshift-telco-core-rds-rhel9
• RHEL Variants: rhel9 (preferred), rhel8

Telco RAN DU RDS (ran)

For Radio Access Network Distributed Unit workloads.

• Image: registry.redhat.io/openshift4/ztp-site-generate-rhel8
• RHEL Variants: rhel8 only

Telco Hub RDS (hub)

For Advanced Cluster Management hub clusters.

• Image: registry.redhat.io/openshift4/openshift-telco-hub-rds-rhel9
• RHEL Variants: rhel9 (preferred), rhel8
• Minimum OpenShift Version: 4.19

Automatic Version Detection

When running inside an OpenShift cluster, the kube_compare_resolve_rds and kube_compare_validate_rds tools can automatically:

1. Detect the cluster's OpenShift version from the ClusterVersion resource
2. Find the matching RDS container image for that version
3. Select the best RHEL variant available (preferring newer versions)
4. Validate the image is accessible before returning

BIOS Reference Configurations

The baremetal_bios_diff tool compares bare metal host BIOS settings against reference ConfigMaps stored on the MCP server cluster. This section describes how to create and deploy these references.

ConfigMap Format

Each reference ConfigMap contains the expected BIOS version and settings for a specific server model and role:

apiVersion: v1
kind: ConfigMap
metadata:
  name: bios-ref-dell-xr8620t-master
  namespace: reference-configs
  labels:
    app.kubernetes.io/name: kube-compare-mcp
    app.kubernetes.io/component: bios-reference
    bios-reference/vendor: dell-inc
    bios-reference/model: xr8620t
    bios-reference/role: master
data:
  biosVersion: "2.19.1"
  settings: |
    BootMode: Uefi
    SysProfile: Custom
    WorkloadProfile: TelcoOptimizedProfile
    SriovGlobalEnable: Enabled
    MadtCoreEnumeration: Linear
    ProcC1E: Disabled
    ProcPwrPerf: OsDbpm

Required fields:

| Field | Description | |-------|-------------| | metadata.name | ConfigMap name, conventionally bios-ref--- | | metadata.namespace | Must match the reference_source parameter (default: reference-configs) | | data.biosVersion |

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sakhoury
• Source: sakhoury/kube-compare-mcp
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.