komodor-mcp 0.1.4

Komodor MCP Server - Intelligent AI assistant for Kubernetes infrastructure

Komodor MCP Server

⚠️ Beta Release: This package is currently in beta. Features and APIs may change in future releases.

A comprehensive MCP (Model Context Protocol) server for Komodor that provides AI assistants with intelligent access to Kubernetes infrastructure monitoring and health analysis data.

🚀 Features

• 🔧 9 Powerful Tools: Complete Kubernetes infrastructure analysis and monitoring
• 📊 Health Monitoring: Real-time cluster health risks and violation analysis
• 🔍 Root Cause Analysis: AI-powered Klaudia RCA for incident investigation
• ⚡ FastMCP Implementation: Modern async architecture with Starlette
• 🛡️ Type-Safe: Full type hints and Pydantic models
• 🌐 Dual Transport: HTTP and stdio transport modes
• 📝 Smart Prompts: Pre-built analysis templates for common scenarios

📦 Installation

Prerequisites

• Python 3.11 or higher
• Komodor account and API key
• uv package manager (recommended) for uvx command

Quick Install with uvx (Recommended)

The easiest way to use Komodor MCP is via uvx, which automatically installs and runs the package:

# Run directly with uvx (no installation needed)
uvx komodor-mcp --transport stdio

uvx will automatically download and install the package from PyPI if it's not already cached, making it perfect for MCP client configurations.

Development Installation

For local development or customization:

# Clone the repository
git clone https://github.com/komodor/komodor-mcp.git
cd komodor-mcp

# Install dependencies
uv sync

# Or with pip
pip install -e .

Environment Setup

Create a .env file in the project root:

# Required: Your Komodor API key
KOMODOR_API_KEY=your-api-key-here

# Optional: API base URL (defaults to production)
KOMODOR_API_BASE_URL=https://api.komodor.com

# Optional: Server configuration
MCP_SERVER_HOST=localhost
MCP_SERVER_PORT=8002
LOG_LEVEL=INFO

🚀 Quick Start

HTTP Transport (Recommended)

# Start the server
uv run komodor-mcp

# Server will be available at http://localhost:8002
# Health check: http://localhost:8002/health
# MCP endpoint: http://localhost:8002/mcp

Stdio Transport (Development)

# For direct MCP client integration
uv run komodor-mcp --transport stdio

🛠️ Available Tools

Cluster Management

• get_clusters() - Retrieve all clusters in your Komodor workspace
• get_services_by(cluster, namespaces, service_kind, status) - Search and filter services by cluster, namespace, or type

Health Analysis

• get_health_risks(cluster_name, namespace, status, check_category, page_size, offset) - Get health violations and risks across clusters
• get_health_risk_data(risk_id) - Detailed analysis of specific health violations
• get_service_yaml(cluster, namespace, kind, name) - Retrieve Kubernetes YAML configurations

Root Cause Analysis

• trigger_klaudia_rca(cluster, namespace, resource_kind, resource_name, wait) - Initiate AI-powered root cause analysis
• get_klaudia_rca_results(session_id, wait) - Retrieve RCA results and recommendations

📊 Resources

• komodor://clusters - Live cluster information resource

🎯 Smart Prompts

Komodor Health Overview

Purpose: Comprehensive health analysis of cluster violations and unhealthy services with actionable recommendations.

What it does:

• Analyzes health risks across clusters and namespaces
• Identifies unhealthy services and patterns
• Provides prioritized action plans
• Categorizes issues by severity (Critical, High, Medium, Low)
• Offers immediate and long-term recommendations

Parameters:

• cluster_name (required): Target cluster for analysis
• namespace (optional): Specific namespace to focus on

Use when: You need a complete health assessment of your Kubernetes infrastructure.

Komodor Root Cause Analysis

Purpose: Perform deep-dive RCA on specific health issues using Klaudia AI analysis.

What it does:

• Initiates AI-powered root cause analysis using Klaudia
• Analyzes service configuration and health risks
• Provides technical analysis with confidence levels
• Offers step-by-step resolution plans
• Maps dependencies and resource constraints

Parameters:

• cluster_name (required): Target cluster
• service_name (required): Service experiencing issues
• namespace (required): Service namespace
• issue_description (optional): Description of the problem

Use when: You have a specific service issue that needs deep investigation and AI-powered insights.

🔧 MCP Client Configuration

Using uvx (Recommended)

The recommended way to use Komodor MCP is via uvx, which automatically handles package installation and execution. This is the simplest and most reliable method for MCP clients.

Cursor IDE

Add to your .cursor/mcp.json:

{
    "mcpServers": {
        "komodor-mcp": {
            "command": "uvx",
            "args": ["komodor-mcp", "--transport", "stdio"],
            "env": {
                "KOMODOR_API_KEY": "your-api-key-here"
            }
        }
    }
}

Claude Desktop

Add to your claude_desktop_config.json:

{
    "mcpServers": {
        "komodor-mcp": {
            "command": "uvx",
            "args": ["komodor-mcp", "--transport", "stdio"],
            "env": {
                "KOMODOR_API_KEY": "your-api-key-here"
            }
        }
    }
}

Generic MCP Client

For stdio transport (recommended):

{
    "command": "uvx",
    "args": ["komodor-mcp", "--transport", "stdio"],
    "env": {
        "KOMODOR_API_KEY": "your-api-key-here"
    }
}

HTTP Transport (Alternative)

If you prefer running the server manually, you can use HTTP transport:

{
    "url": "http://localhost:8002/mcp",
    "headers": {
        "Authorization": "your-api-key-here"
    }
}

Start the server first:

uvx komodor-mcp --transport http
# or
uv run komodor-mcp --transport http

🔍 Usage Examples

Health Analysis

# Get health risks for a specific cluster
health_risks = await get_health_risks(
    cluster_name=["production-cluster"],
    namespace=["default", "monitoring"],
    status=["open", "confirmed"],
    check_category=["workload", "infrastructure"],
    page_size=100,
    offset=0
)

# Get detailed violation data
violation_data = await get_health_risk_data(risk_id="7e3eeda1-b70c-44be-826d-87e68b0d3e2c")

Service Management

# Search for unhealthy services
unhealthy_services = await get_services_by(
    cluster="production-cluster",
    namespaces=["default", "monitoring"],
    service_kind=["Deployment", "StatefulSet"],
    status="unhealthy"
)

# Get service YAML configuration
service_yaml = await get_service_yaml(
    cluster="production-cluster",
    namespace="default",
    kind="Deployment",
    name="nginx-deployment"
)

Root Cause Analysis

# Trigger RCA for a specific resource
rca_response = await trigger_klaudia_rca(
    cluster="production-cluster",
    namespace="default",
    resource_kind="Deployment",
    resource_name="nginx-deployment",
    wait=True
)

# Get RCA results using session ID
rca_results = await get_klaudia_rca_results(
    session_id=rca_response.session_id,
    wait=True
)

🐛 Troubleshooting

Common Issues

Server won't start:

• Verify Python 3.11+ is installed
• Check that KOMODOR_API_KEY is set correctly
• Ensure port 8002 is available

API authentication errors:

• Verify your Komodor API key is valid
• Check that the API key has proper permissions
• Ensure KOMODOR_API_BASE_URL is correct

MCP client connection issues:

• For HTTP transport: Check server is running on correct port
• For stdio transport: Verify environment variables are set
• Check MCP client configuration format

Debug Mode

Enable debug logging:

export LOG_LEVEL=DEBUG
uv run komodor-mcp

Enable remote debugging:

export DEBUG_MODE=true
uv run komodor-mcp
# Attach debugger to localhost:5678

📄 License

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

🆘 Support

• Documentation: Komodor Docs
• Issues: GitHub Issues
• Support: [e-mail]