Skip to main content
Glama

Karma MCP Server

by driosalido
GitHub
Python
MIT License
  • Apple
  • Linux
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

🚨 Karma MCP Server

License: MIT Python 3.11+ MCP Protocol Docker Support Just

Bring AI-powered intelligence to your Kubernetes alerts. Karma MCP Server enables Claude to directly interact with your Karma Alert Dashboard, providing natural language queries, analysis, and management of Prometheus/Alertmanager alerts.

🌟 What is This?

Karma MCP Server is a bridge that connects Claude Desktop (or any MCP-compatible client) to your Karma Alert Dashboard. This allows you to:

  • 🗣️ Ask questions in natural language about your alerts: "How many critical alerts are there in production?"

  • 🔍 Search and filter across multiple Kubernetes clusters simultaneously

  • 📊 Get instant insights about alert patterns and trends

  • 🚀 Accelerate incident response with AI-powered alert analysis

  • 🔄 Automate routine checks without leaving your conversation

Example Interactions with Claude

You: "Show me all critical alerts in the production cluster" Claude: [Lists and analyzes critical alerts with context] You: "Which pods are crash looping?" Claude: [Shows KubePodCrashLooping alerts with namespace, pod details, and suggestions] You: "Search for OOM killed containers across all clusters" Claude: [Performs multi-cluster search and provides memory optimization tips]

🎯 Key Features

Core Alert Management

  • ✅ Real-time alert listing with severity, state, and cluster information

  • ✅ Multi-cluster support - search across all your Kubernetes clusters at once

  • ✅ Smart filtering by cluster, namespace, severity, and alert state

  • ✅ Detailed alert inspection with annotations, labels, and runbook links

  • ✅ Statistical summaries showing alert distribution and trends

Advanced Capabilities

  • 🔍 Alert name search - Search specific alerts by pattern matching

  • 🔍 State filtering - Filter by active, suppressed, or all states

  • 🔍 Cross-cluster analysis - Compare alert patterns between environments

Integration Features

  • 🔄 MCP Protocol support for AI assistants

  • 🐳 Docker support with multi-architecture images

  • ☸️ Kubernetes-ready deployment

📦 Installation

Quick Start with Claude Desktop

  1. Install via UV (recommended)

# Install uv if you haven't already curl -LsSf https://astral.sh/uv/install.sh | sh # Clone and install git clone https://github.com/driosalido/karma-mcp.git cd karma-mcp uv sync --all-extras # Optional: Install Just task runner for easier development brew install just # macOS # See: https://github.com/casey/just#installation for other platforms

  1. Configure Claude Desktop, Claude Code, or Cursor

Local Installation (Stdio Mode)

Add to your MCP client configuration:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{ "mcpServers": { "karma": { "command": "uv", "args": ["run", "python", "-m", "karma_mcp.server"], "cwd": "/path/to/karma-mcp", "env": { "KARMA_URL": "http://your-karma-instance:8080" } } } }

Claude Code (add to project's claude_desktop_config.json or global config):

{ "mcpServers": { "karma": { "command": "uv", "args": ["run", "python", "-m", "karma_mcp.server"], "cwd": "/path/to/karma-mcp", "env": { "KARMA_URL": "http://your-karma-instance:8080" } } } }

Cursor (via MCP extension or custom configuration):

{ "mcpServers": { "karma": { "command": "uv", "args": ["run", "python", "-m", "karma_mcp.server"], "cwd": "/path/to/karma-mcp", "env": { "KARMA_URL": "http://your-karma-instance:8080" } } } }

Remote HTTP Server (Alternative)

If you have deployed the HTTP server version, use SSE transport:

{ "mcpServers": { "karma": { "transport": { "type": "sse", "url": "https://your-karma-mcp-server.com/mcp/sse" } } } }

  1. Connect to your Karma instance

# If Karma is in Kubernetes kubectl port-forward svc/karma 8080:80 -n monitoring # Or set your Karma URL directly export KARMA_URL=http://your-karma-instance:8080

  1. Restart Claude Desktop and start asking about your alerts!

Docker Installation

# Using pre-built image docker run -d \ -e KARMA_URL=http://your-karma:8080 \ -p 8000:8000 \ driosalido/karma-mcp:latest # Or build locally docker build -f docker/Dockerfile -t karma-mcp . docker run -d -e KARMA_URL=http://karma:8080 karma-mcp

Kubernetes Deployment

# Deploy using Docker image kubectl create deployment karma-mcp \ --image=driosalido/karma-mcp:latest kubectl set env deployment/karma-mcp \ KARMA_URL=http://karma.monitoring:80

🛠️ Available MCP Tools

The following tools are available for Claude to use:

Tool

Description

Example Query

check_karma

Verify Karma connectivity

"Is Karma accessible?"

list_alerts

List all active alerts

"Show me all alerts"

get_alerts_summary

Statistical summary by severity/state

"Give me an alert summary"

get_alert_details

Detailed info about specific alert

"Details about KubePodCrashLooping"

list_clusters

List all K8s clusters with counts

"Which clusters have alerts?"

list_alerts_by_cluster

Filter by cluster

"Show teddy-prod alerts"

list_active_alerts

Show only active alerts

"What's currently firing?"

list_suppressed_alerts

Show silenced/inhibited

"What alerts are suppressed?"

get_alerts_by_state

Filter by state (active/suppressed/all)

"Show all suppressed alerts"

search_alerts

Search alerts by name pattern

"Find all OOM alerts"

silence_alert

Create alert silence

"Silence KubePodCrashLooping for 2h"

🧠 AI-Enhanced Analysis

The Karma MCP Server includes specialized prompts that help Claude provide more valuable alert analysis:

📚 Available Prompt Resources

Resource

Purpose

Description

prompts://alert-analysis

Alert Analysis

Comprehensive guidelines for troubleshooting common K8s alerts

prompts://incident-response

Incident Response

Escalation procedures and communication templates

prompts://kubernetes-context

K8s Context

Deep Kubernetes knowledge for alert interpretation

prompts://business-impact

Business Impact

Prioritization framework based on service criticality

🎯 Enhanced Capabilities

With these prompts, Claude can:

  • 🔍 Correlate related alerts across clusters and namespaces

  • 🚨 Prioritize by business impact (prod > staging > dev)

  • 🔧 Suggest specific actions for common alert types

  • 📊 Provide context about Kubernetes resource relationships

  • 🚀 Guide incident response with escalation procedures

🔌 API Integration

The server runs as an MCP server using stdio protocol for communication with Claude Desktop. For programmatic access, you can call the MCP tools directly from your Python code:

from karma_mcp.server import list_alerts, get_alerts_summary # Example usage alerts = await list_alerts() summary = await get_alerts_summary()

🧪 Testing

# Run unit tests uv run pytest tests/unit/ # Run with coverage uv run pytest --cov=karma_mcp tests/ # Run integration tests (requires Karma instance) KARMA_URL=http://localhost:8080 uv run pytest tests/integration/ # Manual testing with real Karma server KARMA_URL=http://localhost:8080 uv run python -c " import asyncio from karma_mcp.server import list_alerts, get_alerts_summary asyncio.run(list_alerts()) "

🔧 Development

Setting up the development environment

# Clone the repository git clone https://github.com/driosalido/karma-mcp.git cd karma-mcp # Install dependencies (includes dev dependencies) uv sync --all-extras # Install Just task runner (modern alternative to Make) # macOS brew install just # Other platforms: https://github.com/casey/just#installation # Set up development environment just dev-setup

Task Runner: Just vs Make

This project uses Just as the modern task runner (alternative to Make). Key benefits:

  • ✅ No tab/space issues (common Make problem)

  • ✅ Better variable handling and environment integration

  • ✅ Cleaner syntax and cross-platform compatibility

  • ✅ Built-in command listing with just

  • ✅ Modern features like default values and string interpolation

# See all available commands just # Common development tasks just test-unit # Run unit tests (78 tests) just lint # Code linting just format # Code formatting just check # All quality checks just test-with-karma # Test with real Karma server just docker-build-local # Build Docker image just version # Show version info

Manual Development Commands

If you prefer direct commands or don't have Just installed:

# Run tests uv run pytest tests/unit/ -v # Code quality uv run ruff check src/ tests/ uv run ruff format src/ tests/ # Install pre-commit hooks uv run pre-commit install

Project Structure

karma-mcp/ ├── src/karma_mcp/ │ └── server.py # Main MCP server with all tools ├── tests/ │ ├── unit/ # Unit tests │ ├── integration/ # Integration tests │ └── fixtures/ # Test data ├── docker/ │ └── Dockerfile # Docker configuration ├── scripts/ │ └── test_karma.py # Integration testing utilities ├── justfile # Modern task runner (preferred) ├── Makefile # Traditional Make tasks (legacy) ├── pyproject.toml # Project dependencies and config └── .github/workflows/ # CI/CD pipelines

📊 Real-World Use Cases

Daily Operations

  • Morning standup: "Show me all critical alerts from the last 24 hours"

  • Shift handover: "Summarize current active alerts by cluster"

  • Quick checks: "Are there any database-related alerts?"

Incident Response

  • Investigation: "Find all alerts related to the payment service"

  • Pattern detection: "Show me crash loops in the API namespace"

  • Impact analysis: "Which clusters are affected by high CPU throttling?"

Capacity Planning

  • Resource issues: "List all OOM killed containers this week"

  • Scaling decisions: "Show pods with high memory pressure"

  • Performance: "Find all high latency alerts"

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Areas we'd love help with:

  • 📈 Historical trending and analytics

  • 🔐 Authentication support for secured Karma instances

  • 🌍 Additional language support for alert descriptions

  • 📱 Slack/Teams notification integrations

  • 🤖 AI-powered alert correlation and root cause analysis

📝 License

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

🙏 Acknowledgments

  • Karma Alert Dashboard - The excellent alert dashboard that makes this possible

  • Model Context Protocol - Anthropic's protocol for AI tool integration

  • FastMCP - Simplified MCP server development

  • The Kubernetes and Prometheus communities for their amazing monitoring ecosystem

📚 Documentation

  • Configuration: Set KARMA_URL environment variable to your Karma instance

  • Troubleshooting: Check the GitHub Issues for common problems

  • Examples: See the "Real-World Use Cases" section above for query examples

🚀 Roadmap

Completed ✅

  • Core alert querying and filtering

  • Multi-cluster support

  • State-based filtering (active/suppressed)

  • Docker containerization

  • CI/CD with GitHub Actions

  • Alert search by pattern

  • Alert silencing capability

In Progress 🔨

  • Alert acknowledgment

  • Silence management (list/delete)

Future Plans 💭

  • Historical data and trending

  • Alert correlation analysis

  • Grafana integration

  • Authentication for secured Karma instances

Need help? Open an issue or reach out on GitHub Discussions

Like this project? Give it a ⭐ on GitHub!

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Enables Claude to interact with Karma Alert dashboard to monitor and analyze Kubernetes alerts. Provides tools to check alert status, filter by cluster/severity, get detailed alert information, and analyze alert statistics and trends.

  1. 🌟 What is This?
    1. Example Interactions with Claude
  2. 🎯 Key Features
    1. Core Alert Management
    2. Advanced Capabilities
    3. Integration Features
  3. 📦 Installation
    1. Quick Start with Claude Desktop
    2. Docker Installation
    3. Kubernetes Deployment
  4. 🛠️ Available MCP Tools
    1. 🧠 AI-Enhanced Analysis
      1. 📚 Available Prompt Resources
      2. 🎯 Enhanced Capabilities
    2. 🔌 API Integration
      1. 🧪 Testing
        1. 🔧 Development
          1. Setting up the development environment
          2. Task Runner: Just vs Make
          3. Manual Development Commands
          4. Project Structure
        2. 📊 Real-World Use Cases
          1. Daily Operations
          2. Incident Response
          3. Capacity Planning
        3. 🤝 Contributing
          1. 📝 License
            1. 🙏 Acknowledgments
              1. 📚 Documentation
                1. 🚀 Roadmap
                  1. Completed ✅
                  2. In Progress 🔨
                  3. Future Plans 💭

                New MCP Servers

                MCP directory API

                We provide all the information about MCP servers via our MCP API.

                curl -X GET 'https://glama.ai/api/mcp/v1/servers/driosalido/mcp-karma'

                If you have feedback or need assistance with the MCP directory API, please join our Discord server