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
1# LUMINO MCP Server23[](https://opensource.org/licenses/Apache-2.0)4[](https://www.python.org/downloads/)5[](https://modelcontextprotocol.io/)6[](https://pypi.org/project/lumino-mcp-server/)78<!-- mcp-name: io.github.geored/lumino -->910An open source MCP (Model Context Protocol) server empowering SREs with intelligent observability, predictive analytics, and AI-driven automation across Kubernetes, OpenShift, and Tekton environments.1112## Table of Contents1314- [Overview](#overview)15- [Features](#features)16- [Quick Start](#quick-start)17- [Prerequisites](#prerequisites)18- [Installation](#installation)19- [Usage Examples](#usage-examples)20- [Configuration](#configuration)21- [Available Tools](#available-tools)22- [Architecture](#architecture)23- [How It Works](#how-it-works)24- [MCP Client Integration](#mcp-client-integration)25- [Performance Considerations](#performance-considerations)26- [Troubleshooting](#troubleshooting)27- [Dependencies](#dependencies)28- [Contributing](#contributing)29- [Security](#security)30- [License](#license)31- [Acknowledgments](#acknowledgments)3233## Overview3435LUMINO 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:3637- **Monitor** cluster health, resources, and pipeline status in real-time38- **Analyze** logs, events, and anomalies using statistical and ML techniques39- **Troubleshoot** failed pipelines with automated root cause analysis40- **Predict** resource bottlenecks and potential issues before they occur41- **Simulate** configuration changes to assess impact before deployment4243## Features4445### Kubernetes & OpenShift Operations46- Namespace and pod management47- Resource querying with flexible output formats48- Label-based resource search across clusters49- OpenShift operator and MachineConfigPool status50- etcd log analysis5152### Tekton Pipeline Intelligence53- Pipeline and task run monitoring across namespaces54- Detailed log retrieval with optional cleaning55- Failed pipeline root cause analysis56- Cross-cluster pipeline tracing57- CI/CD performance baselining5859### Advanced Log Analysis60- Smart log summarization with configurable detail levels61- Streaming analysis for large log volumes62- Hybrid analysis combining multiple strategies63- Semantic search using NLP techniques64- Anomaly detection with severity classification6566### Predictive & Proactive Monitoring67- Statistical anomaly detection using z-score analysis68- Predictive log analysis for early warning69- Resource bottleneck forecasting70- Certificate health monitoring with expiry alerts71- TLS certificate issue investigation7273### Event Intelligence74- Smart event retrieval with multiple strategies75- Progressive event analysis (overview to deep-dive)76- Advanced analytics with ML pattern detection77- Log-event correlation7879### Simulation & What-If Analysis80- Monte Carlo simulation for configuration changes81- Impact analysis before deployment82- Risk assessment with configurable tolerance83- Affected component identification8485## Quick Start8687Get started with LUMINO in under 2 minutes:8889### For Claude Code CLI Users (Easiest)9091Simply ask Claude Code to provision the Lumino MCP server for you by pasting this prompt:9293```94Provision the Lumino MCP server as a project-local MCP integration:95961. Clone the repository:97 git clone https://github.com/spre-sre/lumino-mcp-server.git98992. Install Python dependencies using uv:100 cd lumino-mcp-server && uv sync1011023. Create .mcp.json in the current project root (NOT inside lumino-mcp-server) with this configuration.103 IMPORTANT: Replace <ABSOLUTE_PATH_TO_LUMINO> with the actual absolute path to the cloned lumino-mcp-server directory:104105 {106 "mcpServers": {107 "lumino": {108 "type": "stdio",109 "command": "<ABSOLUTE_PATH_TO_LUMINO>/.venv/bin/python",110 "args": ["<ABSOLUTE_PATH_TO_LUMINO>/main.py"],111 "env": {112 "PYTHONUNBUFFERED": "1"113 }114 }115 }116 }1171184. After creating .mcp.json, inform the user to:119 - Exit Claude Code completely120 - Connect to their Kubernetes or OpenShift cluster (kubectl/oc login)121 - Restart Claude Code in this project directory122 - They will see a prompt to approve the Lumino MCP server123 - Once approved, Lumino tools will be available (check with /mcp command)124```125126### For Other MCP Clients127128Choose your preferred installation method:129- **MCPM (Recommended)**: `mcpm install @spre-sre/lumino-mcp-server`130- **Manual Setup**: See detailed [MCP Client Integration](#mcp-client-integration) instructions131132### Verify Installation133134Once installed, test with a simple query:135136```137"List all namespaces in my Kubernetes cluster"138```139140## Prerequisites141142### Required143- **Python 3.10 or higher** - Core runtime144- **MCP Client** - One of:145 - [Claude Desktop](https://claude.ai/download)146 - [Claude Code CLI](https://github.com/anthropics/claude-code)147 - [Gemini CLI](https://github.com/google/generative-ai-cli)148 - [Cursor IDE](https://cursor.sh/)149150### For Kubernetes Features151- **Kubernetes/OpenShift Access** - Valid kubeconfig with read permissions152- **RBAC Permissions** - Ability to list pods, namespaces, and other resources153154### Optional (Recommended)155- **[uv](https://docs.astral.sh/uv/)** - Faster dependency management than pip156- **[MCPM](https://github.com/spre-sre/mcpm)** - Easiest installation experience157- **Prometheus** - For advanced metrics and forecasting features158159## Installation160161### Using uv (recommended)162163```bash164# Clone the repository165git clone https://github.com/spre-sre/lumino-mcp-server.git166cd lumino-mcp-server167168# Install dependencies169uv sync170171# Run the server172uv run python main.py173```174175### Using pip176177```bash178# Clone the repository179git clone https://github.com/spre-sre/lumino-mcp-server.git180cd lumino-mcp-server181182# Create virtual environment183python -m venv venv184source venv/bin/activate # On Windows: venv\Scripts\activate185186# Install dependencies187pip install -e .188189# Run the server190python main.py191```192193## Usage194195### Local Mode (stdio transport)196197By default, the server runs in local mode using stdio transport, suitable for direct integration with MCP clients:198199```bash200python main.py201```202203### Kubernetes Mode (HTTP streaming transport)204205When running inside Kubernetes, set the namespace environment variable to enable HTTP streaming:206207```bash208export KUBERNETES_NAMESPACE=my-namespace209python main.py210```211212The server automatically detects the environment and switches transport modes.213214## Usage Examples215216### 🔍 Intelligent Root Cause Analysis217218Investigate and diagnose complex failures with automated analysis:219220```221"Generate a comprehensive RCA report for the failed pipeline run 'build-api-pr-456' in namespace ci-cd"222```223224```225"Analyze what caused pod crashes in namespace production over the last 6 hours and correlate with resource events"226```227228```229"Investigate the TLS certificate issues affecting services in namespace ingress-nginx"230```231232### 🎯 Predictive Intelligence & Forecasting233234Anticipate problems before they impact your systems:235236```237"Predict resource bottlenecks across all production namespaces for the next 48 hours"238```239240```241"Analyze historical pipeline performance and detect anomalies in build times for the last 30 days"242```243244```245"Check cluster certificate health and alert me about any certificates expiring in the next 60 days"246```247248```249"Use predictive log analysis to identify potential failures in namespace monitoring before they occur"250```251252### 🧪 Simulation & What-If Analysis253254Test changes safely before applying them to production:255256```257"Simulate the impact of increasing memory limits to 4Gi for all pods in namespace backend-services"258```259260```261"Run a what-if scenario for scaling deployments to 10 replicas and analyze resource consumption"262```263264```265"Simulate configuration changes for nginx ingress controller and assess risk to existing traffic"266```267268### 🗺️ Topology & Dependency Mapping269270Understand system architecture and component relationships:271272```273"Generate a live topology map of all services, deployments, and their dependencies in namespace microservices"274```275276```277"Map the complete dependency graph for the payment-service including all connected resources"278```279280```281"Show me the topology of components affected by the cert-manager service"282```283284### 🔬 Advanced Investigation & Forensics285286Deep-dive into complex issues with multi-faceted analysis:287288```289"Perform an adaptive namespace investigation for production - analyze logs, events, and resource patterns"290```291292```293"Create a detailed investigation report for resource constraints and bottlenecks in namespace data-processing"294```295296```297"Trace pipeline execution for commit SHA abc123def from source to deployment across all namespaces"298```299300```301"Search logs semantically for 'authentication failures related to expired tokens' across the last 24 hours"302```303304### 📊 CI/CD Pipeline Intelligence305306Optimize and troubleshoot your continuous delivery pipelines:307308```309"Establish performance baselines for all Tekton pipelines and flag runs deviating by more than 2 standard deviations"310```311312```313"Trace the complete pipeline flow for image 'api:v2.5.3' from build to production deployment"314```315316```317"Analyze failed pipeline runs in namespace tekton-pipelines and identify common failure patterns"318```319320```321"Compare current pipeline run times against 30-day baseline and highlight performance degradation"322```323324### 🎨 Progressive Event Analysis325326Multi-level event investigation from overview to deep-dive:327328```329"Start with an overview of events in namespace kube-system, then drill down into critical issues"330```331332```333"Perform advanced event analytics with ML pattern detection for namespace monitoring over the last 12 hours"334```335336```337"Correlate events with pod logs to identify the root cause of CrashLoopBackOff in namespace applications"338```339340### 🚀 Real-Time Monitoring & Alerts341342Stay informed about cluster health and pipeline status:343344```345"Show me the status of all Tekton pipeline runs cluster-wide and highlight long-running pipelines"346```347348```349"List all failed TaskRuns in the last hour with error details and recommended actions"350```351352```353"Monitor OpenShift cluster operators and alert on any degraded components"354```355356```357"Check MachineConfigPool status and show which nodes are being updated"358```359360### 🔐 Security & Compliance361362Ensure cluster security and certificate management:363364```365"Scan all namespaces for expiring certificates and generate a renewal schedule"366```367368```369"Investigate TLS certificate issues causing handshake failures in namespace istio-system"370```371372```373"Audit all secrets and configmaps for sensitive data exposure patterns"374```375376### 📈 Advanced Analytics & ML Insights377378Leverage machine learning for pattern detection:379380```381"Use streaming log analysis to process large log volumes from namespace data-pipeline with error pattern detection"382```383384```385"Detect anomalies in log patterns using ML analysis with medium severity threshold for namespace api-gateway"386```387388```389"Analyze resource utilization trends using Prometheus metrics and forecast capacity needs"390```391392## Configuration393394### Kubernetes Authentication395396The server automatically detects Kubernetes configuration:3973981. **In-cluster config** - When running inside a Kubernetes pod3992. **Local kubeconfig** - When running locally (uses `~/.kube/config`)400401### Environment Variables402403| Variable | Description | Default | When to Use |404|----------|-------------|---------|-------------|405| `KUBERNETES_NAMESPACE` | Namespace for K8s mode | - | When running server inside a Kubernetes pod |406| `K8S_NAMESPACE` | Alternative namespace variable | - | Alternative to `KUBERNETES_NAMESPACE` |407| `PROMETHEUS_URL` | Prometheus server URL for metrics | Auto-detected | Custom Prometheus endpoint or non-standard port |408| `KUBECONFIG` | Path to kubeconfig file | `~/.kube/config` | Multiple clusters or custom kubeconfig location |409| `LOG_LEVEL` | Logging verbosity (DEBUG, INFO, WARNING, ERROR) | `INFO` | Debugging issues or reducing log noise |410| `MCP_SERVER_LOG_LEVEL` | MCP framework log level | `INFO` | Troubleshooting MCP protocol issues |411| `PYTHONUNBUFFERED` | Disable Python output buffering | - | Recommended for MCP clients to see real-time logs |412413## Available Tools414415### Kubernetes Core (4 tools)416417| Tool | Description |418|------|-------------|419| `list_namespaces` | List all namespaces in the cluster |420| `list_pods_in_namespace` | List pods with status and placement info |421| `get_kubernetes_resource` | Get any Kubernetes resource with flexible output |422| `search_resources_by_labels` | Search resources across namespaces by labels |423424### Tekton Pipelines (6 tools)425426| Tool | Description |427|------|-------------|428| `list_pipelineruns` | List PipelineRuns with status and timing |429| `list_taskruns` | List TaskRuns, optionally filtered by pipeline |430| `get_pipelinerun_logs` | Retrieve pipeline logs with optional cleaning |431| `list_recent_pipeline_runs` | Recent pipelines across all namespaces |432| `find_pipeline` | Find pipelines by pattern matching |433| `get_tekton_pipeline_runs_status` | Cluster-wide pipeline status summary |434435### Log Analysis (6 tools)436437| Tool | Description |438|------|-------------|439| `analyze_logs` | Extract error patterns from log text |440| `smart_summarize_pod_logs` | Intelligent log summarization |441| `stream_analyze_pod_logs` | Streaming analysis for large logs |442| `analyze_pod_logs_hybrid` | Combined analysis strategies |443| `detect_log_anomalies` | Anomaly detection with severity levels |444| `semantic_log_search` | NLP-based semantic log search |445446### Event Analysis (3 tools)447448| Tool | Description |449|------|-------------|450| `smart_get_namespace_events` | Smart event retrieval with strategies |451| `progressive_event_analysis` | Multi-level event analysis |452| `advanced_event_analytics` | ML-powered event pattern detection |453454### Failure Analysis & RCA (2 tools)455456| Tool | Description |457|------|-------------|458| `analyze_failed_pipeline` | Root cause analysis for failed pipelines |459| `automated_triage_rca_report_generator` | Automated incident reports |460461### Resource Monitoring (4 tools)462463| Tool | Description |464|------|-------------|465| `check_resource_constraints` | Detect resource issues in namespace |466| `detect_anomalies` | Statistical anomaly detection |467| `prometheus_query` | Execute PromQL queries |468| `resource_bottleneck_forecaster` | Predict resource exhaustion |469470### Namespace Investigation (2 tools)471472| Tool | Description |473|------|-------------|474| `conservative_namespace_overview` | Focused namespace health check |475| `adaptive_namespace_investigation` | Dynamic investigation based on query |476477### Certificate & Security (2 tools)478479| Tool | Description |480|------|-------------|481| `investigate_tls_certificate_issues` | Find TLS-related problems |482| `check_cluster_certificate_health` | Certificate expiry monitoring |483484### OpenShift Specific (3 tools)485486| Tool | Description |487|------|-------------|488| `get_machine_config_pool_status` | MachineConfigPool status and updates |489| `get_openshift_cluster_operator_status` | Cluster operator health |490| `get_etcd_logs` | etcd log retrieval and analysis |491492### CI/CD Performance (2 tools)493494| Tool | Description |495|------|-------------|496| `ci_cd_performance_baselining_tool` | Pipeline performance baselines |497| `pipeline_tracer` | Trace pipelines by commit, PR, or image |498499### Topology & Prediction (2 tools)500501| Tool | Description |502|------|-------------|503| `live_system_topology_mapper` | Real-time system topology mapping |504| `predictive_log_analyzer` | Predict issues from log patterns |505506### Simulation (1 tool)507508| Tool | Description |509|------|-------------|510| `what_if_scenario_simulator` | Simulate configuration changes |511512## Architecture513514```515lumino-mcp-server/516├── main.py # Entry point with transport detection517├── src/518│ ├── server-mcp.py # MCP server with all 37 tools519│ └── helpers/520│ ├── constants.py # Shared constants521│ ├── event_analysis.py # Event processing logic522│ ├── failure_analysis.py # RCA algorithms523│ ├── log_analysis.py # Log processing524│ ├── resource_topology.py # Topology mapping525│ ├── semantic_search.py # NLP search526│ └── utils.py # Utility functions527└── pyproject.toml # Project configuration528```529530## How It Works531532LUMINO acts as a bridge between AI assistants and your Kubernetes infrastructure through the Model Context Protocol:533534```535┌─────────────────────────────────────────────────────────────────┐536│ AI Assistant Layer │537│ (Claude Desktop, Claude Code CLI, Gemini CLI) │538└────────────────────────────┬────────────────────────────────────┘539 │540 │ Natural Language Queries541 │ "Analyze failed pipelines"542 │ "Predict resource bottlenecks"543 ▼544┌─────────────────────────────────────────────────────────────────┐545│ Model Context Protocol │546│ (MCP Communication) │547└────────────────────────────┬────────────────────────────────────┘548 │549 │ Tool Invocations & Results550 │551 ▼552┌─────────────────────────────────────────────────────────────────┐553│ LUMINO MCP Server │554│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │555│ │ Log Analysis │ │ Event Intel │ │ Predictive │ │556│ │ (6 tools) │ │ (3 tools) │ │ (2 tools) │ │557│ └──────────────┘ └──────────────┘ └──────────────┘ │558│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │559│ │ Pipeline │ │ Simulation │ │ Topology │ │560│ │ (6 tools) │ │ (1 tool) │ │ (2 tools) │ │561│ └──────────────┘ └──────────────┘ └──────────────┘ │562└────────────────────────────┬────────────────────────────────────┘563 │564 │ Kubernetes API Calls565 │ Prometheus Queries566 │567 ▼568┌─────────────────────────────────────────────────────────────────┐569│ Kubernetes/OpenShift Cluster │570│ │571│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │572│ │ Pods │ │ Services │ │ Tekton │ │etcd/Logs │ │573│ └──────────┘ └──────────┘ │Pipelines │ └──────────┘ │574│ ┌──────────┐ ┌──────────┐ └──────────┘ ┌──────────┐ │575│ │ Events │ │ Configs │ ┌──────────┐ │Prometheus│ │576│ └──────────┘ └──────────┘ │OpenShift │ └──────────┘ │577│ │Operators │ │578│ └──────────┘ │579└─────────────────────────────────────────────────────────────────┘580```581582### Workflow5835841. **User Query** → AI assistant receives natural language request5852. **MCP Translation** → Assistant converts query to appropriate tool calls5863. **LUMINO Processing** → Server executes Kubernetes/Prometheus operations5874. **Data Analysis** → ML/statistical algorithms process raw data5885. **AI Synthesis** → Assistant formats results into human-readable insights589590### Key Features591592- **Stateless Design** - No data persistence, queries cluster in real-time593- **Automatic Transport Detection** - Switches between stdio (local) and HTTP (K8s) modes594- **Token Budget Management** - Adaptive strategies to handle large log volumes595- **Intelligent Caching** - Smart caching for frequently accessed data596- **Security First** - Uses existing kubeconfig RBAC permissions, no separate auth597598## MCP Client Integration599600### Method 1: Using MCPM (Recommended for Claude Code CLI / Gemini CLI)601602The easiest way to install LUMINO MCP Server for Claude Code CLI or Gemini CLI is using [MCPM](https://github.com/spre-sre/mcpm) - an MCP server package manager.603604#### Install MCPM605606```bash607# Clone and build MCPM608git clone https://github.com/spre-sre/mcpm.git609cd mcpm610go build -o mcpm .611612# Optional: Add to PATH613sudo mv mcpm /usr/local/bin/614```615616**Requirements**: Go 1.23+, Git, Python 3.10+, uv (or pip)617618#### Install LUMINO MCP Server619620```bash621# Install from GitHub repository (short syntax)622mcpm install @spre-sre/lumino-mcp-server623624# Or use full GitHub URL625mcpm install https://github.com/spre-sre/lumino-mcp-server.git626627# For GitLab repositories (if hosted on GitLab)628mcpm install gl:@spre-sre/lumino-mcp-server629630# Install for specific client631mcpm install @spre-sre/lumino-mcp-server --claude # For Claude Code CLI632mcpm install @spre-sre/lumino-mcp-server --gemini # For Gemini CLI633634# Install globally (works with both Claude and Gemini)635mcpm install @spre-sre/lumino-mcp-server --global636```637638**Short syntax explained**:639- `@owner/repo` - Installs from GitHub (default: `https://github.com/owner/repo.git`)640- `gl:@owner/repo` - Installs from GitLab (`https://gitlab.com/owner/repo.git`)641- Full URL - Works with any Git repository642643This will:644- Clone the repository to `~/.mcp/servers/lumino-mcp-server/`645- Auto-detect Python project and install dependencies using `uv` (or pip)646- Register with Claude Code CLI or Gemini CLI configuration automatically647648#### Manage LUMINO649650```bash651# List installed servers652mcpm list653654# Update LUMINO655mcpm update lumino-mcp-server656657# Remove LUMINO658mcpm remove lumino-mcp-server659```660661---662663### Method 2: Manual Configuration664665If you prefer manual setup or need to configure Claude Desktop / Cursor, follow these client-specific guides:666667#### Claude Desktop6686691. **Find your config file location**:670 - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`671 - Windows: `%APPDATA%\Claude\claude_desktop_config.json`672 - Linux: `~/.config/Claude/claude_desktop_config.json`6736742. **Add LUMINO configuration**:675676```json677{678 "mcpServers": {679 "lumino": {680 "command": "uv",681 "args": [682 "run",683 "--directory",684 "/path/to/lumino-mcp-server",685 "python",686 "main.py"687 ],688 "env": {689 "PYTHONUNBUFFERED": "1"690 }691 }692 }693}694```6956963. **Restart Claude Desktop**6976984. **Verify**: Look for the hammer icon (🔨) in Claude Desktop to see available tools699700---701702#### Claude Code CLI703704**Option A: Using MCPM** (see Method 1 above)705706**Option B: Automatic Provisioning via Claude Code** (Recommended and easiest way)707708Copy and paste the provisioning prompt from the [Quick Start](#for-claude-code-cli-users-easiest) section above into Claude Code. Claude will clone the repository, install dependencies, and configure the MCP server for your project.709710**Option C: Manual Configuration**7117121. **Clone and install**:713714```bash715git clone https://github.com/spre-sre/lumino-mcp-server.git716cd lumino-mcp-server717uv sync # Creates .venv with all dependencies718```7197202. **Create `.mcp.json`** in your project root (for project-local config) or update `~/.claude.json` (for global config):721722```json723{724 "mcpServers": {725 "lumino": {726 "type": "stdio",727 "command": "/absolute/path/to/lumino-mcp-server/.venv/bin/python",728 "args": ["/absolute/path/to/lumino-mcp-server/main.py"],729 "env": {730 "PYTHONUNBUFFERED": "1"731 }732 }733 }734}735```736737**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`).7387393. **Verify installation**:740741```bash742# Check MCP servers743claude mcp list744745# Test with a query746claude "List all namespaces in my cluster"747```748749---750751#### Gemini CLI752753**Option A: Using MCPM** (Recommended - see Method 1 above)754755**Option B: Manual Configuration**7567571. **Find your config file location**:758 - macOS/Linux: `~/.config/gemini/mcp_servers.json`759 - Windows: `%APPDATA%\gemini\mcp_servers.json`7607612. **Add LUMINO configuration**:762763```json764{765 "mcpServers": {766 "lumino": {767 "command": "uv",768 "args": [769 "run",770 "--directory",771 "/path/to/lumino-mcp-server",772 "python",773 "main.py"774 ],775 "env": {776 "PYTHONUNBUFFERED": "1"777 }778 }779 }780}781```7827833. **Verify installation**:784785```bash786# Check MCP servers787gemini mcp list788789# Test with a query790gemini "Show me failed pipeline runs"791```792793---794795#### Cursor IDE7967971. **Open Cursor Settings**:798 - Press `Cmd+,` (macOS) or `Ctrl+,` (Windows/Linux)799 - Search for "MCP" or "Model Context Protocol"8008012. **Add MCP Server Configuration**:802803In Cursor's MCP settings, add:804805```json806{807 "mcpServers": {808 "lumino": {809 "command": "uv",810 "args": [811 "run",812 "--directory",813 "/path/to/lumino-mcp-server",814 "python",815 "main.py"816 ],817 "env": {818 "PYTHONUNBUFFERED": "1"819 }820 }821 }822}823```824825**Alternative - Using Cursor's settings.json**:8268271. Open Command Palette (`Cmd+Shift+P` or `Ctrl+Shift+P`)8282. Type "Preferences: Open User Settings (JSON)"8293. Add the MCP configuration:830831```json832{833 "mcp.servers": {834 "lumino": {835 "command": "uv",836 "args": [837 "run",838 "--directory",839 "/path/to/lumino-mcp-server",840 "python",841 "main.py"842 ],843 "env": {844 "PYTHONUNBUFFERED": "1"845 }846 }847 }848}849```8508513. **Restart Cursor IDE**8528534. **Verify**: Open Cursor's AI chat and check if LUMINO tools are available854855---856857### Configuration Notes858859**Replace `/path/to/lumino-mcp-server`** with the actual path where you cloned the repository:860861```bash862# Example paths:863# macOS/Linux: /Users/username/projects/lumino-mcp-server864# Windows: C:\Users\username\projects\lumino-mcp-server865866# If installed via MCPM:867# ~/.mcp/servers/lumino-mcp-server/868```869870**Environment Variables** (optional):871872Add these to the `env` section if needed:873874```json875{876 "env": {877 "PYTHONUNBUFFERED": "1",878 "KUBERNETES_NAMESPACE": "default",879 "PROMETHEUS_URL": "http://prometheus:9090",880 "LOG_LEVEL": "INFO"881 }882}883```884885---886887### Using Alternative Python Package Managers888889#### With pip instead of uv890891```json892{893 "command": "python",894 "args": [895 "/path/to/lumino-mcp-server/main.py"896 ]897}898```899900**Note**: Ensure you've activated the virtual environment first:901902```bash903cd /path/to/lumino-mcp-server904python -m venv venv905source venv/bin/activate # On Windows: venv\Scripts\activate906pip install -e .907```908909#### With poetry910911```json912{913 "command": "poetry",914 "args": [915 "run",916 "python",917 "main.py"918 ],919 "cwd": "/path/to/lumino-mcp-server"920}921```922923---924925### Testing Your Configuration926927After configuring any client, test the connection:9289291. **Check if tools are loaded**:930 - Claude Desktop: Look for 🔨 hammer icon931 - Claude Code CLI: `claude mcp list`932 - Gemini CLI: `gemini mcp list`933 - Cursor: Check AI chat for available tools9349352. **Test a simple query**:936937```938"List all namespaces in my Kubernetes cluster"939```9409413. **Check server logs** (if issues):942943```bash944# Run server manually to see errors945cd /path/to/lumino-mcp-server946uv run python main.py947```948949Expected output:950```951MCP Server running in stdio mode952Available tools: 37953Waiting for requests...954```955956---957958### Advanced Configuration959960#### Multiple Clusters961962Configure multiple LUMINO instances for different clusters:963964```json965{966 "mcpServers": {967 "lumino-prod": {968 "command": "uv",969 "args": ["run", "--directory", "/path/to/lumino-mcp-server", "python", "main.py"],970 "env": {971 "KUBECONFIG": "/path/to/prod-kubeconfig.yaml"972 }973 },974 "lumino-dev": {975 "command": "uv",976 "args": ["run", "--directory", "/path/to/lumino-mcp-server", "python", "main.py"],977 "env": {978 "KUBECONFIG": "/path/to/dev-kubeconfig.yaml"979 }980 }981 }982}983```984985#### Custom Log Level986987```json988{989 "env": {990 "LOG_LEVEL": "DEBUG",991 "MCP_SERVER_LOG_LEVEL": "DEBUG"992 }993}994```995996---997998### Supported Transports9991000The server automatically detects the appropriate transport:10011002- **stdio** - For local desktop integrations (Claude Desktop, Claude Code CLI, Gemini CLI, Cursor)1003- **streamable-http** - For Kubernetes deployments (when `KUBERNETES_NAMESPACE` is set)10041005## Performance Considerations10061007### Optimizing for Large Clusters10081009LUMINO is designed to handle clusters of any size efficiently:10101011| Cluster Size | Recommendation | Tool Strategy |1012|--------------|----------------|---------------|1013| **Small** (< 50 pods) | Use default settings | All tools work optimally |1014| **Medium** (50-500 pods) | Use namespace filtering | Leverage adaptive tools with auto-sampling |1015| **Large** (500+ pods) | Specify time windows and namespaces | Use conservative and streaming tools |1016| **Very Large** (1000+ pods) | Combine filters and pagination | Progressive analysis with targeted queries |10171018### Token Budget Management10191020LUMINO automatically manages AI context limits:10211022- **Adaptive Sampling** - Smart tools auto-sample data when volumes are high1023- **Progressive Loading** - Stream analysis processes data in chunks1024- **Token Budgets** - Configurable limits prevent context overflow1025- **Hybrid Strategies** - Automatically selects best analysis approach10261027### Query Optimization Tips10281029**Use Namespace Filtering**1030```1031✅ "Analyze logs for pods in namespace production"1032❌ "Analyze all pod logs in the cluster"1033```10341035**Specify Time Windows**1036```1037✅ "Show events from the last 2 hours"1038❌ "Show all events" (might return thousands)1039```10401041**Leverage Smart Tools**1042```1043✅ "smart_summarize_pod_logs" - Adaptive analysis1044❌ Direct log dumps - No processing1045```10461047**Use Progressive Analysis**1048```1049✅ Start with "overview" → drill down to "detailed"1050❌ Jump directly to "deep_dive" on large datasets1051```10521053### Performance Metrics10541055| Operation | Typical Response Time | Scalability |1056|-----------|----------------------|-------------|1057| List namespaces | < 1s | O(1) |1058| Get pod logs (1 pod) | 1-3s | O(log size) |1059| Analyze pipeline run | 2-5s | O(task count) |1060| Cluster-wide search | 5-15s | O(namespace count) |1061| ML anomaly detection | 3-10s | O(data points) |1062| Topology mapping | 5-20s | O(resource count) |10631064### Caching Strategy10651066LUMINO uses intelligent caching for frequently accessed data:10671068- **15-minute cache** - For web-fetched content1069- **Session cache** - For hybrid log analysis1070- **No persistence** - All data queries cluster in real-time10711072### Concurrent Requests10731074The server handles multiple concurrent requests efficiently:10751076- **Thread-safe operations** - Safe parallel tool execution1077- **Connection pooling** - Reuses Kubernetes API connections1078- **Async HTTP** - Non-blocking Prometheus queries10791080### Resource Usage10811082**Server Resource Requirements**10831084| Deployment | CPU | Memory | Disk |1085|------------|-----|--------|------|1086| Local (stdio) | 100-500m | 256-512Mi | Minimal |1087| Kubernetes | 200m-1 | 512Mi-1Gi | Minimal |1088| High-load | 1-2 | 1-2Gi | Minimal |10891090**Note**: LUMINO is stateless and requires minimal resources. Most processing happens in the AI assistant.10911092## Troubleshooting10931094### Common Issues10951096**No Kubernetes cluster found**1097```1098Error: Unable to load kubeconfig1099```1100Ensure you have a valid kubeconfig at `~/.kube/config` or are running inside a cluster.11011102**Permission denied for resources**1103```1104Error: Forbidden - User cannot list resource1105```1106Check your RBAC permissions. The server needs read access to the resources you want to query.11071108**Tool timeout**1109For large clusters, some tools may timeout. Use filtering options (namespace, labels) to reduce scope.11101111## Dependencies11121113- `mcp[cli]>=1.10.1` - Model Context Protocol SDK1114- `kubernetes>=32.0.1` - Kubernetes Python client1115- `pandas>=2.0.0` - Data analysis1116- `scikit-learn>=1.6.1` - ML algorithms1117- `prometheus-client>=0.22.0` - Prometheus integration1118- `aiohttp>=3.12.2` - Async HTTP client11191120## Contributing11211122Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) before submitting pull requests.11231124## Security11251126For security vulnerabilities, please see our [Security Policy](SECURITY.md).11271128## License11291130This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.11311132## Acknowledgments11331134- Built with [FastMCP](https://github.com/jlowin/fastmcp) framework1135- Inspired by the needs of SRE teams managing complex Kubernetes environments1136
Full transparency — inspect the skill content before installing.