Lumino

by spre-sre

307 downloads Not rated yet

GitHub Website

About

AI/ML-powered diagnostic engine for SRE Observability on Konflux and OpenShift. It uses the Model Context Protocol (MCP) and 40+ tools to analyze logs, metrics, and traces, enabling automated RCA and predictive analysis.

Explore

- Stateless Design - No data persistence, queries cluster in real-time
- Automatic Transport Detection - Switches between stdio (local) and HTTP (K8s) modes
- Token Budget Management - Adaptive strategies to handle large log volumes
- Intelligent Caching - Smart caching for frequently accessed data
- Security First - Uses existing kubeconfig RBAC permissions, no separate auth

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name Lumino

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

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

JSON

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

JSON

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

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

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

JSON

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

JSON

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

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

From the repository

Get started with LUMINO in under 2 minutes:

Once installed, test with a simple query:

"List all namespaces in my Kubernetes cluster"

uv sync

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

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)

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

bash

mcpm install @spre-sre/lumino-mcp-server

mcpm install @spre-sre/lumino-mcp-server --claude # For Claude Code CLI
mcpm install @spre-sre/lumino-mcp-server --gemini # For Gemini CLI

mcpm install @spre-sre/lumino-mcp-server --global

Short syntax explained: - @owner/repo - Installs from GitHub (default: https://github.com/owner/repo.git) - gl:@owner/repo - Installs from GitLab (https://gitlab.com/owner/repo.git) - Full URL - Works with any Git repository This will: - Clone the repository to ~/.mcp/servers/lumino-mcp-server/ - Auto-detect Python project and install dependencies using uv (or pip) - Register with Claude Code CLI or Gemini CLI configuration automatically mcpm list If you prefer manual setup or need to configure Claude Desktop / Cursor, follow these client-specific guides: Replace /path/to/lumino-mcp-server with the actual path where you cloned the repository:

bash

After configuring any client, test the connection:

1. Check if tools are loaded:
- Claude Desktop: Look for 🔨 hammer icon
- Claude Code CLI: claude mcp list
- Gemini CLI: gemini mcp list
- Cursor: Check AI chat for available tools

2. Test a simple query:

"List all namespaces in my Kubernetes cluster"

3. Check server logs (if issues):

```bash

Server Resource Requirements

| Deployment | CPU | Memory | Disk |
|------------|-----|--------|------|
| Local (stdio) | 100-500m | 256-512Mi | Minimal |
| Kubernetes | 200m-1 | 512Mi-1Gi | Minimal |
| High-load | 1-2 | 1-2Gi | Minimal |

Note: LUMINO is stateless and requires minimal resources. Most processing happens in the AI assistant.

`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

`list_pipelineruns`

List PipelineRuns with status and timing

`list_taskruns`

List TaskRuns, optionally filtered by pipeline

`get_pipelinerun_logs`

Retrieve pipeline logs with optional cleaning

`list_recent_pipeline_runs`

Recent pipelines across all namespaces

`find_pipeline`

Find pipelines by pattern matching

`get_tekton_pipeline_runs_status`

Cluster-wide pipeline status summary

`analyze_logs`

Extract error patterns from log text

`smart_summarize_pod_logs`

Intelligent log summarization

`stream_analyze_pod_logs`

Streaming analysis for large logs

`analyze_pod_logs_hybrid`

Combined analysis strategies

`detect_log_anomalies`

Anomaly detection with severity levels

`semantic_log_search`

NLP-based semantic log search

`smart_get_namespace_events`

Smart event retrieval with strategies

`progressive_event_analysis`

Multi-level event analysis

`advanced_event_analytics`

ML-powered event pattern detection

`analyze_failed_pipeline`

Root cause analysis for failed pipelines

`automated_triage_rca_report_generator`

Automated incident reports

`check_resource_constraints`

Detect resource issues in namespace

`detect_anomalies`

Statistical anomaly detection

`prometheus_query`

Execute PromQL queries

`resource_bottleneck_forecaster`

Predict resource exhaustion

`conservative_namespace_overview`

Focused namespace health check

`adaptive_namespace_investigation`

Dynamic investigation based on query

`investigate_tls_certificate_issues`

Find TLS-related problems

`check_cluster_certificate_health`

Certificate expiry monitoring

`get_machine_config_pool_status`

MachineConfigPool status and updates

`get_openshift_cluster_operator_status`

Cluster operator health

`get_etcd_logs`

etcd log retrieval and analysis

`ci_cd_performance_baselining_tool`

Pipeline performance baselines

`pipeline_tracer`

Trace pipelines by commit, PR, or image

`live_system_topology_mapper`

Real-time system topology mapping

`predictive_log_analyzer`

Predict issues from log patterns

`what_if_scenario_simulator`

Simulate configuration changes

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

| Tool | Description |
|------|-------------|
| list_pipelineruns | List PipelineRuns with status and timing |
| list_taskruns | List TaskRuns, optionally filtered by pipeline |
| get_pipelinerun_logs | Retrieve pipeline logs with optional cleaning |
| list_recent_pipeline_runs | Recent pipelines across all namespaces |
| find_pipeline | Find pipelines by pattern matching |
| get_tekton_pipeline_runs_status | Cluster-wide pipeline status summary |

| Tool | Description |
|------|-------------|
| analyze_logs | Extract error patterns from log text |
| smart_summarize_pod_logs | Intelligent log summarization |
| stream_analyze_pod_logs | Streaming analysis for large logs |
| analyze_pod_logs_hybrid | Combined analysis strategies |
| detect_log_anomalies | Anomaly detection with severity levels |
| semantic_log_search | NLP-based semantic log search |

| Tool | Description |
|------|-------------|
| smart_get_namespace_events | Smart event retrieval with strategies |
| progressive_event_analysis | Multi-level event analysis |
| advanced_event_analytics | ML-powered event pattern detection |

| Tool | Description |
|------|-------------|
| analyze_failed_pipeline | Root cause analysis for failed pipelines |
| automated_triage_rca_report_generator | Automated incident reports |

| Tool | Description |
|------|-------------|
| check_resource_constraints | Detect resource issues in namespace |
| detect_anomalies | Statistical anomaly detection |
| prometheus_query | Execute PromQL queries |
| resource_bottleneck_forecaster | Predict resource exhaustion |

| Tool | Description |
|------|-------------|
| conservative_namespace_overview | Focused namespace health check |
| adaptive_namespace_investigation | Dynamic investigation based on query |

| Tool | Description |
|------|-------------|
| investigate_tls_certificate_issues | Find TLS-related problems |
| check_cluster_certificate_health | Certificate expiry monitoring |

| Tool | Description |
|------|-------------|
| get_machine_config_pool_status | MachineConfigPool status and updates |
| get_openshift_cluster_operator_status | Cluster operator health |
| get_etcd_logs | etcd log retrieval and analysis |

| Tool | Description |
|------|-------------|
| ci_cd_performance_baselining_tool | Pipeline performance baselines |
| pipeline_tracer | Trace pipelines by commit, PR, or image |

| Tool | Description |
|------|-------------|
| live_system_topology_mapper | Real-time system topology mapping |
| predictive_log_analyzer | Predict issues from log patterns |

| Tool | Description |
|------|-------------|
| what_if_scenario_simulator | Simulate configuration changes |

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

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

McpServers

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

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.

- Overview
- Features
- Quick Start
- Prerequisites
- Installation
- Usage Examples
- Configuration
- Available Tools
- Architecture
- How It Works
- MCP Client Integration
- Performance Considerations
- Troubleshooting
- Dependencies
- Contributing
- Security
- License
- Acknowledgments

Overview

LUMINO MCP Server transforms how Site Reliability Engineers (SREs) and DevOps teams interact with Kubernetes clusters. By exposing 37 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)

```bash

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Explore

Setting up with Highlight

From the repository

list_namespaces

list_pods_in_namespace

get_kubernetes_resource

search_resources_by_labels

list_pipelineruns

list_taskruns

get_pipelinerun_logs

list_recent_pipeline_runs

find_pipeline

get_tekton_pipeline_runs_status

analyze_logs

smart_summarize_pod_logs

stream_analyze_pod_logs

analyze_pod_logs_hybrid

detect_log_anomalies

semantic_log_search

smart_get_namespace_events

progressive_event_analysis

advanced_event_analytics

analyze_failed_pipeline

automated_triage_rca_report_generator

check_resource_constraints

detect_anomalies

prometheus_query

resource_bottleneck_forecaster

conservative_namespace_overview

adaptive_namespace_investigation

investigate_tls_certificate_issues

check_cluster_certificate_health

get_machine_config_pool_status

get_openshift_cluster_operator_status

get_etcd_logs

ci_cd_performance_baselining_tool

pipeline_tracer

live_system_topology_mapper

predictive_log_analyzer

what_if_scenario_simulator

Claude Desktop / Cursor

McpServers

Table of Contents

Overview

Features

Kubernetes & OpenShift Operations

Tekton Pipeline Intelligence

Advanced Log Analysis

Predictive & Proactive Monitoring

Event Intelligence

Simulation & What-If Analysis

Quick Start

For Claude Code CLI Users (Easiest)

For Other MCP Clients

Verify Installation

Prerequisites

Required

For Kubernetes Features

Optional (Recommended)

Installation

Using uv (recommended)

More like this

Sentry

Github

Git

GitLab

`list_namespaces`

`list_pods_in_namespace`

`get_kubernetes_resource`

`search_resources_by_labels`

`list_pipelineruns`

`list_taskruns`

`get_pipelinerun_logs`

`list_recent_pipeline_runs`

`find_pipeline`

`get_tekton_pipeline_runs_status`

`analyze_logs`

`smart_summarize_pod_logs`

`stream_analyze_pod_logs`

`analyze_pod_logs_hybrid`

`detect_log_anomalies`

`semantic_log_search`

`smart_get_namespace_events`

`progressive_event_analysis`

`advanced_event_analytics`

`analyze_failed_pipeline`

`automated_triage_rca_report_generator`

`check_resource_constraints`

`detect_anomalies`

`prometheus_query`

`resource_bottleneck_forecaster`

`conservative_namespace_overview`

`adaptive_namespace_investigation`

`investigate_tls_certificate_issues`

`check_cluster_certificate_health`

`get_machine_config_pool_status`

`get_openshift_cluster_operator_status`

`get_etcd_logs`

`ci_cd_performance_baselining_tool`

`pipeline_tracer`

`live_system_topology_mapper`

`predictive_log_analyzer`

`what_if_scenario_simulator`