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

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

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:

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)

Using pip

Usage

Local Mode (stdio transport)

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

Kubernetes Mode (HTTP streaming transport)

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

The server automatically detects the environment and switches transport modes.

Usage Examples

🔍 Intelligent Root Cause Analysis

Investigate and diagnose complex failures with automated analysis:

🎯 Predictive Intelligence & Forecasting

Anticipate problems before they impact your systems:

🧪 Simulation & What-If Analysis

Test changes safely before applying them to production:

🗺️ Topology & Dependency Mapping

Understand system architecture and component relationships:

🔬 Advanced Investigation & Forensics

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

📊 CI/CD Pipeline Intelligence

Optimize and troubleshoot your continuous delivery pipelines:

🎨 Progressive Event Analysis

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

🚀 Real-Time Monitoring & Alerts

Stay informed about cluster health and pipeline status:

🔐 Security & Compliance

Ensure cluster security and certificate management:

📈 Advanced Analytics & ML Insights

Leverage machine learning for pattern detection:

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

Available Tools

Kubernetes Core (4 tools)

Tekton Pipelines (6 tools)

Log Analysis (6 tools)

Event Analysis (3 tools)

Failure Analysis & RCA (2 tools)

Resource Monitoring (4 tools)

Namespace Investigation (2 tools)

Certificate & Security (2 tools)

OpenShift Specific (3 tools)

CI/CD Performance (2 tools)

Topology & Prediction (2 tools)

Simulation (1 tool)

Architecture

How It Works

LUMINO acts as a bridge between AI assistants and your Kubernetes infrastructure through the Model Context Protocol:

Workflow

1. User Query → AI assistant receives natural language request

2. MCP Translation → Assistant converts query to appropriate tool calls

3. LUMINO Processing → Server executes Kubernetes/Prometheus operations

4. Data Analysis → ML/statistical algorithms process raw data

5. AI Synthesis → Assistant formats results into human-readable insights

Key Features

• 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

MCP Client Integration

Method 1: Using MCPM (Recommended for Claude Code CLI / Gemini CLI)

The easiest way to install LUMINO MCP Server for Claude Code CLI or Gemini CLI is using MCPM - an MCP server package manager.

Install MCPM

Requirements: Go 1.23+, Git, Python 3.10+, uv (or pip)

Install LUMINO MCP Server

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

Manage LUMINO

Method 2: Manual Configuration

If you prefer manual setup or need to configure Claude Desktop / Cursor, follow these client-specific guides:

Claude Desktop

1. Find your config file location:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add LUMINO configuration:

3. Restart Claude Desktop

4. Verify: Look for the hammer icon (🔨) in Claude Desktop to see available tools

Claude Code CLI

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

1. Clone and install:

2. Create in your project root (for project-local config) or update ~/.claude.json (for global config):

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

3. Verify installation:

Gemini CLI

Option A: Using MCPM (Recommended - see Method 1 above)

Option B: Manual Configuration

1. Find your config file location:

   • macOS/Linux: ~/.config/gemini/mcp_servers.json

   • Windows: %APPDATA%\gemini\mcp_servers.json

2. Add LUMINO configuration:

3. Verify installation:

Cursor IDE

1. Open Cursor Settings:

   • Press Cmd+, (macOS) or Ctrl+, (Windows/Linux)

   • Search for "MCP" or "Model Context Protocol"

2. Add MCP Server Configuration:

In Cursor's MCP settings, add:

Alternative - Using Cursor's settings.json:

1. Open Command Palette (Cmd+Shift+P or Ctrl+Shift+P)

2. Type "Preferences: Open User Settings (JSON)"

3. Add the MCP configuration:

3. Restart Cursor IDE

4. Verify: Open Cursor's AI chat and check if LUMINO tools are available

Configuration Notes

Replace with the actual path where you cloned the repository:

Environment Variables (optional):

Add these to the env section if needed:

Using Alternative Python Package Managers

With pip instead of uv

Note: Ensure you've activated the virtual environment first:

With poetry

Testing Your Configuration

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:

3. Check server logs (if issues):

Expected output:

Advanced Configuration

Multiple Clusters

Configure multiple LUMINO instances for different clusters:

Custom Log Level

Supported Transports

The server automatically detects the appropriate transport:

• stdio - For local desktop integrations (Claude Desktop, Claude Code CLI, Gemini CLI, Cursor)

• streamable-http - For Kubernetes deployments (when KUBERNETES_NAMESPACE is set)

Performance Considerations

Optimizing for Large Clusters

LUMINO is designed to handle clusters of any size efficiently:

Token Budget Management

LUMINO automatically manages AI context limits:

• Adaptive Sampling - Smart tools auto-sample data when volumes are high

• Progressive Loading - Stream analysis processes data in chunks

• Token Budgets - Configurable limits prevent context overflow

• Hybrid Strategies - Automatically selects best analysis approach

Query Optimization Tips

Use Namespace Filtering

Specify Time Windows

Leverage Smart Tools

Use Progressive Analysis

Performance Metrics

Caching Strategy

LUMINO uses intelligent caching for frequently accessed data:

• 15-minute cache - For web-fetched content

• Session cache - For hybrid log analysis

• No persistence - All data queries cluster in real-time

Concurrent Requests

The server handles multiple concurrent requests efficiently:

• Thread-safe operations - Safe parallel tool execution

• Connection pooling - Reuses Kubernetes API connections

• Async HTTP - Non-blocking Prometheus queries

Resource Usage

Server Resource Requirements

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

Troubleshooting

Common Issues

No Kubernetes cluster found

Ensure you have a valid kubeconfig at ~/.kube/config or are running inside a cluster.

Permission denied for resources

Check your RBAC permissions. The server needs read access to the resources you want to query.

Tool timeout For large clusters, some tools may timeout. Use filtering options (namespace, labels) to reduce scope.

Dependencies

• mcp[cli]>=1.10.1 - Model Context Protocol SDK

• kubernetes>=32.0.1 - Kubernetes Python client

• pandas>=2.0.0 - Data analysis

• scikit-learn>=1.6.1 - ML algorithms

• prometheus-client>=0.22.0 - Prometheus integration

• aiohttp>=3.12.2 - Async HTTP client

Contributing

Contributions are welcome! Please read our Contributing Guide before submitting pull requests.

Security

For security vulnerabilities, please see our Security Policy.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Acknowledgments

• Built with FastMCP framework

• Inspired by the needs of SRE teams managing complex Kubernetes environments