LUMINO MCP Server

An open source MCP (Model Context Protocol) server empowering SREs with intelligent observability, predictive analytics, and AI-driven automation across Kubernetes, OpenShift, and Tekton environments.

Table of Contents

• Overview
• Features
• Quick Start
• Team Onboarding Guide
• Prerequisites
• Installation
• Usage Examples
• Configuration
• ML Model Persistence
• KubeArchive Integration
• Prometheus/Thanos Integration
• Available Tools
• Architecture
• How It Works
• MCP Client Integration
• Performance Considerations
• Troubleshooting
• Dependencies
• Contributing
• Security
• License
• Acknowledgments

Team Onboarding Guide

New to the SPRE MCP diagnostics stack (Lumino, PagerDuty, Slack, DevLake, ngit-memory, GitHub, GitLab, Konflux Portal, Sumo Logic, Jira)? Start here:

• docs/ONBOARDING_GUIDE.md — setup, first diagnostic, troubleshooting, three worked examples, and expected tool outputs

Overview

LUMINO MCP Server transforms how Site Reliability Engineers (SREs) and DevOps teams interact with Kubernetes clusters. By exposing 39 specialized tools through the Model Context Protocol, it enables AI assistants to:

• Monitor cluster health, resources, and pipeline status in real-time
• Analyze logs, events, and anomalies using statistical and ML techniques
• Troubleshoot failed pipelines with automated root cause analysis
• Predict resource bottlenecks and potential issues before they occur
• Simulate configuration changes to assess impact before deployment

Features

Kubernetes & OpenShift Operations

• Namespace and pod management
• Resource querying with flexible output formats
• Label-based resource search across clusters
• OpenShift operator and MachineConfigPool status
• etcd log analysis

Tekton Pipeline Intelligence

• Pipeline and task run monitoring across namespaces
• Detailed log retrieval with optional cleaning
• Failed pipeline root cause analysis
• Cross-cluster pipeline tracing
• CI/CD performance baselining

Advanced Log Analysis

• Smart log summarization with configurable detail levels
• Streaming analysis for large log volumes
• Hybrid analysis combining multiple strategies
• Semantic search using NLP techniques
• Anomaly detection with severity classification

Predictive & Proactive Monitoring

• Statistical anomaly detection using z-score analysis
• Predictive log analysis for early warning
• Resource bottleneck forecasting
• Certificate health monitoring with expiry alerts
• TLS certificate issue investigation

Event Intelligence

• Smart event retrieval with multiple strategies
• Progressive event analysis (overview to deep-dive)
• Advanced analytics with ML pattern detection
• Log-event correlation

Simulation & What-If Analysis

• Monte Carlo simulation for configuration changes
• Impact analysis before deployment
• Risk assessment with configurable tolerance
• Affected component identification

Quick Start

Get started with LUMINO in under 2 minutes:

For Claude Code CLI Users (Easiest)

Simply ask Claude Code to provision the Lumino MCP server for you by pasting this prompt:

Provision the Lumino MCP server as a project-local MCP integration:

1. Clone the repository:
   git clone https://github.com/spre-sre/lumino-mcp-server.git

2. Install Python dependencies using uv:
   cd lumino-mcp-server && uv sync

3. Create .mcp.json in the current project root (NOT inside lumino-mcp-server) with this configuration.
   IMPORTANT: Replace <ABSOLUTE_PATH_TO_LUMINO> with the actual absolute path to the cloned lumino-mcp-server directory:

   {
     "mcpServers": {
       "lumino": {
         "type": "stdio",
         "command": "<ABSOLUTE_PATH_TO_LUMINO>/.venv/bin/python",
         "args": ["<ABSOLUTE_PATH_TO_LUMINO>/main.py"],
         "env": {
           "PYTHONUNBUFFERED": "1"
         }
       }
     }
   }

4. After creating .mcp.json, inform the user to:
   - Exit Claude Code completely
   - Connect to their Kubernetes or OpenShift cluster (kubectl/oc login)
   - Restart Claude Code in this project directory
   - They will see a prompt to approve the Lumino MCP server
   - Once approved, Lumino tools will be available (check with /mcp command)

For Other MCP Clients

Choose your preferred installation method:

• MCPM (Recommended): mcpm install @spre-sre/lumino-mcp-server
• Manual Setup: See detailed MCP Client Integration instructions

Verify Installation

Once installed, test with a simple query:

"List all namespaces in my Kubernetes cluster"

Prerequisites

Required

• Python 3.10 or higher - Core runtime
• MCP Client - One of:
  • Claude Desktop
  • Claude Code CLI
  • Gemini CLI
  • Cursor IDE

For Kubernetes Features

• Kubernetes/OpenShift Access - Valid kubeconfig with read permissions
• RBAC Permissions - Ability to list pods, namespaces, and other resources

Optional (Recommended)

• uv - Faster dependency management than pip
• MCPM - Easiest installation experience
• Prometheus - For advanced metrics and forecasting features

Installation

Using uv (recommended)

# Clone the repository
git clone https://github.com/spre-sre/lumino-mcp-server.git
cd lumino-mcp-server

# Install dependencies
uv sync

# Run the server
uv run python main.py

Using pip

# Clone the repository
git clone https://github.com/spre-sre/lumino-mcp-server.git
cd lumino-mcp-server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e .

# Run the server
python main.py

Usage

Local Mode (stdio transport)

By default, the server runs in local mode using stdio transport, suitable for direct integration with MCP clients:

python main.py

Kubernetes Mode (HTTP streaming transport)

When running inside Kubernetes, set the namespace environment variable to enable HTTP streaming:

export KUBERNETES_NAMESPACE=my-namespace
python main.py

The server automatically detects the environment and switches transport modes.

Usage Examples

🔍 Intelligent Root Cause Analysis

Investigate and diagnose complex failures with automated analysis:

"Generate a comprehensive RCA report for the failed pipeline run 'build-api-pr-456' in namespace ci-cd"

"Analyze what caused pod crashes in namespace production over the last 6 hours and correlate with resource events"

"Investigate the TLS certificate issues affecting services in namespace ingress-nginx"

🎯 Predictive Intelligence & Forecasting

Anticipate problems before they impact your systems:

"Predict resource bottlenecks across all production namespaces for the next 48 hours"

"Analyze historical pipeline performance and detect anomalies in build times for the last 30 days"

"Check cluster certificate health and alert me about any certificates expiring in the next 60 days"

"Use predictive log analysis to identify potential failures in namespace monitoring before they occur"

🧪 Simulation & What-If Analysis

Test changes safely before applying them to production:

"Simulate the impact of increasing memory limits to 4Gi for all pods in namespace backend-services"

"Run a what-if scenario for scaling deployments to 10 replicas and analyze resource consumption"

"Simulate configuration changes for nginx ingress controller and assess risk to existing traffic"

🗺️ Topology & Dependency Mapping

Understand system architecture and component relationships:

"Generate a live topology map of all services, deployments, and their dependencies in namespace microservices"

"Map the complete dependency graph for the payment-service including all connected resources"

"Show me the topology of components affected by the cert-manager service"

🔬 Advanced Investigation & Forensics

Deep-dive into complex issues with multi-faceted analysis:

"Perform an adaptive namespace investigation for production - analyze logs, events, and resource patterns"

"Create a detailed investigation report for resource constraints and bottlenecks in namespace data-processing"

"Trace pipeline execution for commit SHA abc123def from source to deployment across all namespaces"

"Search logs semantically for 'authentication failures related to expired tokens' across the last 24 hours"

📊 CI/CD Pipeline Intelligence

Optimize and troubleshoot your continuous delivery pipelines:

"Establish performance baselines for all Tekton pipelines and flag runs deviating by more than 2 standard deviations"

"Trace the complete pipeline flow for image 'api:v2.5.3' from build to production deployment"

"Analyze failed pipeline runs in namespace tekton-pipelines and identify common failure patterns"

"Compare current pipeline run times against 30-day baseline and highlight performance degradation"

🎨 Progressive Event Analysis

Multi-level event investigation from overview to deep-dive:

"Start with an overview of events in namespace kube-system, then drill down into critical issues"

"Perform advanced event analytics with ML pattern detection for namespace monitoring over the last 12 hours"

"Correlate events with pod logs to identify the root cause of CrashLoopBackOff in namespace applications"

🚀 Real-Time Monitoring & Alerts

Stay informed about cluster health and pipeline status:

"Show me the status of all Tekton pipeline runs cluster-wide and highlight long-running pipelines"

"List all failed TaskRuns in the last hour with error details and recommended actions"

"Monitor OpenShift cluster operators and alert on any degraded components"

"Check MachineConfigPool status and show which nodes are being updated"

🔐 Security & Compliance

Ensure cluster security and certificate management:

"Scan all namespaces for expiring certificates and generate a renewal schedule"

"Investigate TLS certificate issues causing handshake failures in namespace istio-system"

"Audit all secrets and configmaps for sensitive data exposure patterns"

📈 Advanced Analytics & ML Insights

Leverage machine learning for pattern detection:

"Use streaming log analysis to process large log volumes from namespace data-pipeline with error pattern detection"

"Detect anomalies in log patterns using ML analysis with medium severity threshold for namespace api-gateway"

"Analyze resource utilization trends using Prometheus metrics and forecast capacity needs"

Configuration

Kubernetes Authentication

The server automatically detects Kubernetes configuration:

1. In-cluster config - When running inside a Kubernetes pod
2. Local kubeconfig - When running locally (uses ~/.kube/config)

Environment Variables

Variable	Description	Default	When to Use
KUBERNETES_NAMESPACE	Namespace for K8s mode	-	When running server inside a Kubernetes pod
K8S_NAMESPACE	Alternative namespace variable	-	Alternative to KUBERNETES_NAMESPACE
PROMETHEUS_URL	Prometheus server URL for metrics	Auto-detected	Custom Prometheus endpoint or non-standard port
KUBECONFIG	Path to kubeconfig file	~/.kube/config	Multiple clusters or custom kubeconfig location
LOG_LEVEL	Logging verbosity (DEBUG, INFO, WARNING, ERROR)	INFO	Debugging issues or reducing log noise
MCP_SERVER_LOG_LEVEL	MCP framework log level	INFO	Troubleshooting MCP protocol issues
PYTHONUNBUFFERED	Disable Python output buffering	-	Recommended for MCP clients to see real-time logs
KUBEARCHIVE_HOST	Explicit KubeArchive API endpoint URL	Auto-detected	Custom KubeArchive endpoint or non-standard deployment
KUBEARCHIVE_ENABLED	Enable/disable KubeArchive integration	true	Set to false to disable KubeArchive queries entirely
THANOS_URL	Thanos Query endpoint URL (highest priority for metrics)	Auto-detected	Custom Thanos Query endpoint; takes precedence over PROMETHEUS_URL
PROMETHEUS_TOKEN	Bearer token for Prometheus/Thanos authentication	Auto-detected	Explicit auth token when auto-detection fails
OPENSHIFT_TOKEN	OpenShift bearer token for Prometheus/Thanos	Auto-detected	Alternative to PROMETHEUS_TOKEN for OpenShift clusters
OC_TOKEN	OpenShift CLI token fallback	Auto-detected	Last-resort token fallback for Prometheus/Thanos auth

ML Model Persistence

The predictive_log_analyzer tool persists trained ML models and training data locally in ~/.lumino/. This enables model reuse across server restarts and incremental learning from historical failure patterns.

Directory Structure

~/.lumino/
├── models/                     # Trained ML models
│   ├── {model_id}.joblib       # Serialized model (e.g. IsolationForest via joblib)
│   ├── {model_id}.meta.json    # Model metadata (created, last used, performance metrics)
│   └── model_index.json        # Index tracking all models and the current active model
└── training_data/              # Training data store
    └── training_data.db        # SQLite database

Model IDs follow the pattern predictive_log_v1_YYYYMMDD_HHMMSS.

Training Data Database

The SQLite database (training_data.db) contains four tables:

Table	Purpose
log_samples	Preprocessed log samples with extracted features, namespace, pod name, error indicators, and message entropy
failure_labels	Failure events collected from Kubernetes events, failed PipelineRuns, and unhealthy pod statuses. Failure types include: oom, crash, image, scheduling, storage, config, health, network, timeout, pipeline_failure, permission, resource_limits, general, pod_failure
log_failure_correlations	Time-proximity correlations between log samples and failure events (scored 0.5--1.0 based on temporal distance within a 30-minute window)
training_runs	Training run history recording model_id, samples used, labels used, performance metrics, and completion status

All four tables define a cluster_id column for multi-cluster support. Currently, only log_samples and failure_labels actively populate it during writes; log_failure_correlations and training_runs leave it NULL. The cluster ID is derived from the active kubeconfig context name (e.g. api-stone-prod-p02-hjvn-p1-openshiftapps-com:6443) or falls back to in-cluster-{KUBERNETES_SERVICE_HOST} when running inside a pod.

Clearing Stale Data

Programmatic cleanup via the manage_prediction_training_data tool (action cleanup):

• cleanup_old_models(max_age_days=30, keep_min=3) -- removes models older than 30 days, always keeping the 3 most recent
• cleanup_old_data(max_age_days=90) -- removes log samples, failure labels, and correlations older than 90 days

Manual cleanup:

rm -rf ~/.lumino/              # Clear everything (models + training data)
rm -rf ~/.lumino/models/       # Clear just models
rm -rf ~/.lumino/training_data/ # Clear just training data (SQLite DB)

Disk usage note: Models accumulate over time. The default cleanup keeps models up to 30 days old with a minimum of 3 retained. Training data is kept for 90 days. Run the manage_prediction_training_data tool with action cleanup periodically to reclaim disk space.

KubeArchive Integration

KubeArchive stores Kubernetes resources off-cluster and provides a REST API for historical resource states and logs. LUMINO uses KubeArchive as a fallback when pods, PipelineRuns, or TaskRuns have been garbage-collected from the live cluster. The query_kubearchive tool queries this archive transparently.

Endpoint Auto-Discovery

The endpoint is discovered automatically using a 5-step chain (first match wins):

1. KUBEARCHIVE_HOST environment variable (highest priority)
2. OpenShift Route named kubearchive-api-server in namespaces: kubearchive, product-kubearchive, default
3. Kubernetes Ingress named kubearchive-api-server in the same namespaces
4. Kubernetes Service named kubearchive-api-server (in-cluster DNS: https://kubearchive-api-server.<namespace>.svc.cluster.local:<port>)
5. Kubeconfig-based Route inference -- constructs candidate URLs from the API server domain (pattern: https://kubearchive-api-server-{namespace}.apps.{cluster-domain}) and probes /livez

Results are cached at startup. On connection failure, the cache is cleared and re-probed on the next request.

Local Development (Port-Forwarding)

When running outside the cluster, if an in-cluster Service endpoint is discovered (step 4), LUMINO automatically sets up kubectl port-forward:

kubectl port-forward -n {namespace} svc/kubearchive-api-server {local_port}:{remote_port}

• Tries ports 8081--8090, then falls back to a system-assigned port
• The port-forward process is auto-started and auto-cleaned up on server exit
• If kubectl is not available, LUMINO logs a manual fallback command for the user

Authentication

KubeArchive authentication uses the following priority chain:

1. Provided token (from constructor / previous session)
2. In-cluster service account token (/var/run/secrets/kubernetes.io/serviceaccount/token)
3. Existing Kubernetes client token (extracted from the API client initialized at server startup)
4. OpenShift oc whoami -t token (for OpenShift clusters)
5. Auto-created short-lived service account token (kubectl create token, 1-hour duration, Kubernetes only)

Resource Management & Cleanup

The KubeArchiveEndpointDiscovery class implements robust subprocess cleanup for kubectl port-forward processes to prevent resource leaks.

Recommended Usage: Context Manager

Use the with statement for deterministic cleanup:

from src.helpers.kubearchive_integration import KubeArchiveEndpointDiscovery

with KubeArchiveEndpointDiscovery(k8s_core_api, k8s_custom_api) as discovery:
    endpoint = await discovery.discover_endpoint()
    # Use the endpoint...
    # Port-forward subprocess automatically cleaned up on exit

Automatic Cleanup Layers

When used without explicit context management, the class provides three fallback cleanup mechanisms:

1. atexit handler — Cleans up port-forward on normal interpreter shutdown
2. Signal handlers (SIGTERM/SIGINT) — Graceful cleanup on termination, chains to original handlers
3. __del__ finalizer — Last-resort fallback (not guaranteed timing)

The context manager approach is preferred for deterministic resource cleanup.

KubeArchive Configuration

See the Configuration section above for KUBEARCHIVE_HOST and KUBEARCHIVE_ENABLED environment variables.

Prometheus/Thanos Integration

LUMINO auto-discovers Prometheus or Thanos Query endpoints for the prometheus_query, resource_bottleneck_forecaster, and ci_cd_performance_baselining_tool tools. Thanos Query implements the Prometheus HTTP API and is preferred when available since it provides a unified, deduplicated view across replicas.

Endpoint Discovery Priority

Priority	Source	Endpoint Type
0	THANOS_URL env var	thanos
1	PROMETHEUS_URL env var	prometheus
2	Predefined cluster endpoints (in code)	varies
3	5-minute TTL cache	cached
4	Auto-discovery chain (see below)	detected
5	Predefined fallback endpoints	varies

Auto-discovery order depends on runtime environment:

• In-cluster: Thanos services --> Prometheus services --> Prometheus Operator CRD --> OpenShift Routes
• Local/outside cluster: OpenShift Routes --> Thanos services --> Prometheus Operator CRD --> Prometheus services

Auto-Discovery Details

OpenShift Routes: Searches the openshift-monitoring namespace. Prefers the thanos-querier route over prometheus-k8s. Falls back to any route with prometheus in the name. Detects protocol from TLS termination config.

Thanos Services: Searches namespaces openshift-monitoring, monitoring, thanos, observability, kube-prometheus. Priority service names: thanos-query-frontend, thanos-querier, thanos-query. Also searches via label selectors: app.kubernetes.io/name=thanos-query, app.kubernetes.io/component=query,app.kubernetes.io/name=thanos, app=thanos-query, app=thanos-querier.

Prometheus Services: Searches namespaces openshift-monitoring, monitoring, prometheus, kube-prometheus, observability. Priority service names: prometheus-server, prometheus-k8s, prometheus. Also searches via label selectors: app=prometheus, app.kubernetes.io/name=prometheus, app.kubernetes.io/component=prometheus.

Prometheus Operator CRD: Discovers via monitoring.coreos.com/v1 Prometheus custom resources and their associated services (pattern: prometheus-{name} in the same namespace).

Prometheus/Thanos Authentication

Authentication for Prometheus/Thanos uses the following 5 methods in priority order:

1. oc whoami -t -- fresh OpenShift token (most reliable for OpenShift)
2. Re-read kubeconfig file for current token
3. In-memory Kubernetes client config token
4. ServiceAccount token file (/var/run/secrets/kubernetes.io/serviceaccount/token)
5. Environment variables: PROMETHEUS_TOKEN, OPENSHIFT_TOKEN, OC_TOKEN (checked in that order)

Configuration Example

{
  "env": {
    "THANOS_URL": "https://thanos-querier.example.com",
    "PROMETHEUS_TOKEN": "your-bearer-token"
  }
}

Note: The endpoint cache has a 5-minute TTL. If you change THANOS_URL or PROMETHEUS_URL at runtime, the new value takes effect on the next query.

Available Tools

Kubernetes Core (5 tools)

Tool	Description
list_namespaces	List all namespaces in the cluster
list_pods_in_namespace	List pods with status and placement info
get_kubernetes_resource	Get any Kubernetes resource with flexible output
search_resources_by_labels	Search resources across namespaces by labels
query_kubearchive	Query archived Kubernetes resources from KubeArchive with optional log retrieval

Tekton Pipelines (6 tools)