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: