OpenShift MCP Server

A Model Context Protocol (MCP) server for monitoring and managing OpenShift/Kubernetes clusters. This server provides real-time cluster insights through AI IDE, enabling natural language queries about your cluster health, performance, and resource usage.

🤖 Generated by Cursor - AI-powered code editor
Visit cursor.sh to learn more

Features

Core Monitoring Capabilities

• Cluster Health Monitoring: Check overall cluster health and identify stability issues
• Performance Metrics: Retrieve real-time performance metrics for nodes and pods
• Resource Issue Detection: Detect pods and nodes with resource allocation problems
• Pod Disruption Analysis: Analyze pod disruptions and restart patterns
• Node Condition Monitoring: Check node conditions and identify problematic nodes
• Deployment Monitoring: Monitor deployment status and rollout health

Remote Execution Capabilities for Advanced Performance Testing and Benchmarking

• Bastion Host Support: Execute tests on private clusters through jump hosts
• SSH Integration: Secure remote command execution with credential management
• Multi-Cluster Testing: Test across different OpenShift environments
• Automated Benchmarking: Schedule and run performance tests through AI IDE
• Remote Execution: Execute performance benchmarks and tools on remote clusters through bastion hosts
• Multi-Cluster Support: Manage and test across different OpenShift environments

Prerequisites

• Node.js 18+
• Access to an OpenShift/Kubernetes cluster
• Valid kubeconfig file or in-cluster configuration
• SSH access to bastion hosts (for remote deployments)

Bastion Host Authentication Setup

For remote cluster access through bastion hosts, you can use either SSH key (recommended) or password authentication:

Option 1: SSH Key Authentication (Recommended)

1. Generate SSH key pair (if you don't have one):

   ssh-keygen -t ed25519 -f ~/.ssh/id_rsa_bastion -C "mcp-server-access"

2. Copy public key to bastion host:

   ssh-copy-id -i ~/.ssh/id_rsa_bastion.pub user@your-bastion-host.com

3. Test SSH connectivity:

   ssh -i ~/.ssh/id_rsa_bastion user@your-bastion-host.com

4. Configure MCP environment variables:

   export MCP_BASTION_HOST="your-bastion-host.com"
   export MCP_BASTION_USER="your-username"
   export MCP_SSH_KEY="~/.ssh/id_rsa_bastion"

Option 2: Password Authentication (Optional)

For environments where SSH keys are not feasible:

1. Install sshpass (required for password authentication):

   # Ubuntu/Debian
   sudo apt-get install sshpass
   
   # macOS
   brew install sshpass
   
   # RHEL/CentOS
   sudo yum install sshpass

2. Configure MCP environment variables:

   export MCP_BASTION_HOST="your-bastion-host.com"
   export MCP_BASTION_USER="your-username"
   export MCP_BASTION_PASSWORD="your-secure-password"

Security Note: SSH key authentication is strongly recommended over password authentication for better security. Password authentication should only be used when SSH keys are not available.

Installation

npm install

Configuration

The server uses the standard Kubernetes client configuration methods:

1. KUBECONFIG environment variable: Set the path to your kubeconfig file

   export KUBECONFIG=/path/to/your/kubeconfig

2. Default kubeconfig location: ~/.kube/config

3. In-cluster configuration: When running inside a Kubernetes pod

Usage

Running the Server

npm start

Or directly:

node index.js

Using with AI IDE

Once the MCP server is configured in your AI IDE, you can interact with your OpenShift cluster using natural language:

Monitoring & Health Checks

• "Check the overall health of the OpenShift cluster"
• "Show me the current node conditions"
• "Are there any resource issues in the cluster?"
• "Monitor deployment status in the production namespace"
• "Get performance metrics for the last hour"
• "Analyze pod disruptions in the default namespace"

Deploy cluster objects

• "Create a new deployment with guaranteed QoS using 4 CPU cores in namespace test-ns"
• "Deploy a PostgreSQL database with persistent storage in the production namespace"
• "Create a service mesh configuration for microservices communication"
• "Set up a horizontal pod autoscaler for the web application"
• "Deploy monitoring stack with Prometheus and Grafana"
• "Create network policies to secure pod-to-pod communication"
• "Set up ingress controllers and SSL termination"
• "Deploy a Redis cluster with high availability configuration"

Run performance tools and benchmarks (may require tool integration)

• "Execute cluster density testing with kube-burner to measure application deployment performance"
• "Run storage performance benchmarks using FIO workloads"
• "Test network throughput between pods using iperf3"
• "Perform CPU and memory stress testing on worker nodes"
• "Execute database performance tests with sysbench or pgbench"
• "Run comprehensive cluster health validation before production deployment"
• "Benchmark container startup times and resource allocation"
• "Test cluster recovery scenarios and failover mechanisms"

Available Tools

1. check_cluster_health

   • Check overall OpenShift cluster health
   • Parameters: detailed (boolean, optional)

2. get_performance_metrics

   • Retrieve current performance metrics
   • Parameters: namespace (string, optional), timeRange (string, default: "1h")

3. detect_resource_issues

   • Detect resource allocation issues
   • Parameters: thresholds (object with cpu, memory, restarts limits)

4. analyze_pod_disruptions

   • Analyze pod disruptions and restart patterns
   • Parameters: namespace (string, optional), hours (number, default: 24)

5. check_node_conditions

   • Check node conditions and identify issues
   • Parameters: none

6. monitor_deployments

   • Monitor deployment status and health
   • Parameters: namespace (string, optional)

Example Usage with MCP Client

// Check cluster health
{
  "method": "tools/call",
  "params": {
    "name": "check_cluster_health",
    "arguments": {
      "detailed": true
    }
  }
}

// Get performance metrics
{
  "method": "tools/call",
  "params": {
    "name": "get_performance_metrics",
    "arguments": {
      "namespace": "production",
      "timeRange": "1h"
    }
  }
}

Examples

Performance Testing Integration

For detailed examples of extending the MCP server with performance testing capabilities, see:

• Kube-Burner Integration Example - Comprehensive guide for integrating kube-burner-ocp performance testing tools

This example demonstrates how to:

• Add remote performance testing capabilities
• Execute benchmarks through Cursor IDE
• Collect and analyze performance metrics
• Implement best practices for different cluster types

Development

Project Structure

cursor-kube-mcp-server/
├── index.js              # Main MCP server implementation
├── package.json          # Node.js dependencies and scripts
├── package-lock.json     # Dependency lock file
├── README.md             # This file
├── .gitignore            # Git ignore patterns
├── docker/               # Docker configuration
│   ├── Dockerfile        # Container image definition
│   └── docker-compose.yml # Development setup
└── kubernetes/           # Kubernetes deployment manifests
    ├── deployment.yaml   # Server deployment
    ├── service.yaml      # Service definition
    ├── configmap.yaml    # Configuration
    └── rbac.yaml         # RBAC permissions

Adding New Tools

1. Add the tool definition to the ListToolsRequestSchema handler
2. Add the implementation case to the CallToolRequestSchema handler
3. Implement the tool method in the class

Error Handling

The server includes comprehensive error handling for:

• Kubernetes API connection issues
• Authentication/authorization problems
• Resource access failures
• Malformed requests

Deployment

Docker

Build and run using Docker:

docker build -f docker/Dockerfile -t openshift-mcp-server .
docker run -v ~/.kube/config:/root/.kube/config openshift-mcp-server

Kubernetes

Deploy to your OpenShift/Kubernetes cluster:

kubectl apply -f kubernetes/

Security Considerations

• The server requires cluster-wide read permissions
• Use appropriate RBAC configurations in production
• Secure kubeconfig files and service account tokens
• Consider network policies for pod-to-pod communication

Troubleshooting

Common Issues

1. Authentication Errors

   • Verify kubeconfig file path and validity
   • Check service account permissions

2. Connection Timeouts

   • Verify cluster connectivity
   • Check firewall and network policies

3. Missing Metrics

   • Ensure metrics-server is deployed
   • Verify metrics API availability

Debugging

Enable debug logging:

export DEBUG=*
node index.js

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

ISC License - see package.json for details

Quick Reference

Available Commands

Command	Description	Example Usage
check_cluster_health	Validate cluster health	"Check cluster health"
get_performance_metrics	Get current performance data	"Get performance metrics for last hour"
detect_resource_issues	Find resource problems	"Are there any resource issues?"
analyze_pod_disruptions	Analyze pod restart patterns	"Show pod disruptions in namespace X"
check_node_conditions	Check node health status	"What are the current node conditions?"
monitor_deployments	Monitor deployment status	"Check deployment status in test namespace"

Configuration Examples

Cursor MCP Configuration

SSH Key Authentication (Recommended):

{
  "mcpServers": {
    "openshift-mcp-server": {
      "command": "node",
      "args": ["/path/to/openshift-mcp-server/index.js"],
      "env": {
        "KUBECONFIG": "/path/to/kubeconfig",
        "MCP_BASTION_HOST": "your-bastion-host",
        "MCP_BASTION_USER": "admin",
        "MCP_SSH_KEY": "~/.ssh/id_rsa"
      }
    }
  }
}

Password Authentication (Optional):

{
  "mcpServers": {
    "openshift-mcp-server": {
      "command": "node",
      "args": ["/path/to/openshift-mcp-server/index.js"],
      "env": {
        "KUBECONFIG": "/path/to/kubeconfig",
        "MCP_BASTION_HOST": "your-bastion-host",
        "MCP_BASTION_USER": "admin",
        "MCP_BASTION_PASSWORD": "your-secure-password"
      }
    }
  }
}

Environment Variables

SSH Key Authentication:

export KUBECONFIG=/path/to/kubeconfig
export MCP_BASTION_HOST=bastion.example.com
export MCP_BASTION_USER=admin
export MCP_SSH_KEY=~/.ssh/id_rsa

Password Authentication:

export KUBECONFIG=/path/to/kubeconfig
export MCP_BASTION_HOST=bastion.example.com
export MCP_BASTION_USER=admin
export MCP_BASTION_PASSWORD=your-secure-password

Support

For issues and questions:

• Check the troubleshooting section
• Review Kubernetes/OpenShift documentation
• Review kube-burner-ocp documentation
• File an issue in the repository