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. - Quick Start - Prerequisites - Installation - Usage Examples - Configuration - Available Tools - Architecture - How It Works - MCP Client Integration - Performance Considerations - Troubleshooting -
Add this skill
npx mdskills install spre-sre/lumino-mcp-serverComprehensive SRE toolkit with 37 tools for Kubernetes observability, predictive analytics, and CI/CD intelligence
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.
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:
Get started with LUMINO in under 2 minutes:
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 with the actual absolute path to the cloned lumino-mcp-server directory:
{
"mcpServers": {
"lumino": {
"type": "stdio",
"command": "/.venv/bin/python",
"args": ["/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)
Choose your preferred installation method:
mcpm install @spre-sre/lumino-mcp-serverOnce installed, test with a simple query:
"List all namespaces in my Kubernetes cluster"
# 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
# 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
By default, the server runs in local mode using stdio transport, suitable for direct integration with MCP clients:
python main.py
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.
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"
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"
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"
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"
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"
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"
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"
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"
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"
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"
The server automatically detects Kubernetes configuration:
~/.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 |
| 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 |
lumino-mcp-server/
βββ main.py # Entry point with transport detection
βββ src/
β βββ server-mcp.py # MCP server with all 37 tools
β βββ helpers/
β βββ constants.py # Shared constants
β βββ event_analysis.py # Event processing logic
β βββ failure_analysis.py # RCA algorithms
β βββ log_analysis.py # Log processing
β βββ resource_topology.py # Topology mapping
β βββ semantic_search.py # NLP search
β βββ utils.py # Utility functions
βββ pyproject.toml # Project configuration
LUMINO acts as a bridge between AI assistants and your Kubernetes infrastructure through the Model Context Protocol:
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β AI Assistant Layer β
β (Claude Desktop, Claude Code CLI, Gemini CLI) β
ββββββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββ
β
β Natural Language Queries
β "Analyze failed pipelines"
β "Predict resource bottlenecks"
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Model Context Protocol β
β (MCP Communication) β
ββββββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββ
β
β Tool Invocations & Results
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β LUMINO MCP Server β
β ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ β
β β Log Analysis β β Event Intel β β Predictive β β
β β (6 tools) β β (3 tools) β β (2 tools) β β
β ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ β
β ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ β
β β Pipeline β β Simulation β β Topology β β
β β (6 tools) β β (1 tool) β β (2 tools) β β
β ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ β
ββββββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββ
β
β Kubernetes API Calls
β Prometheus Queries
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Kubernetes/OpenShift Cluster β
β β
β ββββββββββββ ββββββββββββ ββββββββββββ ββββββββββββ β
β β Pods β β Services β β Tekton β βetcd/Logs β β
β ββββββββββββ ββββββββββββ βPipelines β ββββββββββββ β
β ββββββββββββ ββββββββββββ ββββββββββββ ββββββββββββ β
β β Events β β Configs β ββββββββββββ βPrometheusβ β
β ββββββββββββ ββββββββββββ βOpenShift β ββββββββββββ β
β βOperators β β
β ββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
The easiest way to install LUMINO MCP Server for Claude Code CLI or Gemini CLI is using MCPM - an MCP server package manager.
# Clone and build MCPM
git clone https://github.com/spre-sre/mcpm.git
cd mcpm
go build -o mcpm .
# Optional: Add to PATH
sudo mv mcpm /usr/local/bin/
Requirements: Go 1.23+, Git, Python 3.10+, uv (or pip)
# Install from GitHub repository (short syntax)
mcpm install @spre-sre/lumino-mcp-server
# Or use full GitHub URL
mcpm install https://github.com/spre-sre/lumino-mcp-server.git
# For GitLab repositories (if hosted on GitLab)
mcpm install gl:@spre-sre/lumino-mcp-server
# Install for specific client
mcpm install @spre-sre/lumino-mcp-server --claude # For Claude Code CLI
mcpm install @spre-sre/lumino-mcp-server --gemini # For Gemini CLI
# Install globally (works with both Claude and Gemini)
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)This will:
~/.mcp/servers/lumino-mcp-server/uv (or pip)# List installed servers
mcpm list
# Update LUMINO
mcpm update lumino-mcp-server
# Remove LUMINO
mcpm remove lumino-mcp-server
If you prefer manual setup or need to configure Claude Desktop / Cursor, follow these client-specific guides:
Find your config file location:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json~/.config/Claude/claude_desktop_config.jsonAdd LUMINO configuration:
{
"mcpServers": {
"lumino": {
"command": "uv",
"args": [
"run",
"--directory",
"/path/to/lumino-mcp-server",
"python",
"main.py"
],
"env": {
"PYTHONUNBUFFERED": "1"
}
}
}
}
Restart Claude Desktop
Verify: Look for the hammer icon (π¨) in Claude Desktop to see available tools
Option A: Using MCPM (see Method 1 above)
Option B: Automatic Provisioning via Claude Code (Recommended and easiest way)
Copy and paste the provisioning prompt from the Quick Start section above into Claude Code. Claude will clone the repository, install dependencies, and configure the MCP server for your project.
Option C: Manual Configuration
git clone https://github.com/spre-sre/lumino-mcp-server.git
cd lumino-mcp-server
uv sync # Creates .venv with all dependencies
.mcp.json in your project root (for project-local config) or update ~/.claude.json (for global config):{
"mcpServers": {
"lumino": {
"type": "stdio",
"command": "/absolute/path/to/lumino-mcp-server/.venv/bin/python",
"args": ["/absolute/path/to/lumino-mcp-server/main.py"],
"env": {
"PYTHONUNBUFFERED": "1"
}
}
}
}
Important: Replace /absolute/path/to/lumino-mcp-server with the actual absolute path where you cloned the repository (e.g., /Users/username/projects/lumino-mcp-server).
# Check MCP servers
claude mcp list
# Test with a query
claude "List all namespaces in my cluster"
Option A: Using MCPM (Recommended - see Method 1 above)
Option B: Manual Configuration
Find your config file location:
~/.config/gemini/mcp_servers.json%APPDATA%\gemini\mcp_servers.jsonAdd LUMINO configuration:
{
"mcpServers": {
"lumino": {
"command": "uv",
"args": [
"run",
"--directory",
"/path/to/lumino-mcp-server",
"python",
"main.py"
],
"env": {
"PYTHONUNBUFFERED": "1"
}
}
}
}
# Check MCP servers
gemini mcp list
# Test with a query
gemini "Show me failed pipeline runs"
Open Cursor Settings:
Cmd+, (macOS) or Ctrl+, (Windows/Linux)Add MCP Server Configuration:
In Cursor's MCP settings, add:
{
"mcpServers": {
"lumino": {
"command": "uv",
"args": [
"run",
"--directory",
"/path/to/lumino-mcp-server",
"python",
"main.py"
],
"env": {
"PYTHONUNBUFFERED": "1"
}
}
}
}
Alternative - Using Cursor's settings.json:
Cmd+Shift+P or Ctrl+Shift+P){
"mcp.servers": {
"lumino": {
"command": "uv",
"args": [
"run",
"--directory",
"/path/to/lumino-mcp-server",
"python",
"main.py"
],
"env": {
"PYTHONUNBUFFERED": "1"
}
}
}
}
Restart Cursor IDE
Verify: Open Cursor's AI chat and check if LUMINO tools are available
Replace /path/to/lumino-mcp-server with the actual path where you cloned the repository:
# Example paths:
# macOS/Linux: /Users/username/projects/lumino-mcp-server
# Windows: C:\Users\username\projects\lumino-mcp-server
# If installed via MCPM:
# ~/.mcp/servers/lumino-mcp-server/
Environment Variables (optional):
Add these to the env section if needed:
{
"env": {
"PYTHONUNBUFFERED": "1",
"KUBERNETES_NAMESPACE": "default",
"PROMETHEUS_URL": "http://prometheus:9090",
"LOG_LEVEL": "INFO"
}
}
{
"command": "python",
"args": [
"/path/to/lumino-mcp-server/main.py"
]
}
Note: Ensure you've activated the virtual environment first:
cd /path/to/lumino-mcp-server
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -e .
{
"command": "poetry",
"args": [
"run",
"python",
"main.py"
],
"cwd": "/path/to/lumino-mcp-server"
}
After configuring any client, test the connection:
Check if tools are loaded:
claude mcp listgemini mcp listTest a simple query:
"List all namespaces in my Kubernetes cluster"
# Run server manually to see errors
cd /path/to/lumino-mcp-server
uv run python main.py
Expected output:
MCP Server running in stdio mode
Available tools: 37
Waiting for requests...
Configure multiple LUMINO instances for different clusters:
{
"mcpServers": {
"lumino-prod": {
"command": "uv",
"args": ["run", "--directory", "/path/to/lumino-mcp-server", "python", "main.py"],
"env": {
"KUBECONFIG": "/path/to/prod-kubeconfig.yaml"
}
},
"lumino-dev": {
"command": "uv",
"args": ["run", "--directory", "/path/to/lumino-mcp-server", "python", "main.py"],
"env": {
"KUBECONFIG": "/path/to/dev-kubeconfig.yaml"
}
}
}
}
{
"env": {
"LOG_LEVEL": "DEBUG",
"MCP_SERVER_LOG_LEVEL": "DEBUG"
}
}
The server automatically detects the appropriate transport:
KUBERNETES_NAMESPACE is set)LUMINO is designed to handle clusters of any size efficiently:
| Cluster Size | Recommendation | Tool Strategy |
|---|---|---|
| Small (=1.10.1` - Model Context Protocol SDK |
kubernetes>=32.0.1 - Kubernetes Python clientpandas>=2.0.0 - Data analysisscikit-learn>=1.6.1 - ML algorithmsprometheus-client>=0.22.0 - Prometheus integrationaiohttp>=3.12.2 - Async HTTP clientContributions are welcome! Please read our Contributing Guide before submitting pull requests.
For security vulnerabilities, please see our Security Policy.
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
Install via CLI
npx mdskills install spre-sre/lumino-mcp-serverLUMINO MCP Server is a free, open-source AI agent skill. 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. - Quick Start - Prerequisites - Installation - Usage Examples - Configuration - Available Tools - Architecture - How It Works - MCP Client Integration - Performance Considerations - Troubleshooting -
Install LUMINO MCP Server with a single command:
npx mdskills install spre-sre/lumino-mcp-serverThis downloads the skill files into your project and your AI agent picks them up automatically.
LUMINO MCP Server works with Claude Code, Claude Desktop, Cursor, Vscode Copilot, Windsurf, Continue Dev, Gemini Cli, Amp, Roo Code, Goose. Skills use the open SKILL.md format which is compatible with any AI coding agent that reads markdown instructions.