redhat-performance/openshift-mcp-server

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 Code Assistant, 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 Code Assistant
• 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 Setup

For remote cluster access through bastion hosts, follow these two setup phases:

Phase 1: 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"
   export MCP_REMOTE_PATH="/opt/openshift-mcp-server"
   export MCP_REMOTE_KUBECONFIG="/path/to/remote/kubeconfig"
   export MCP_REMOTE_NODE_ENV="production"
   

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"
   export MCP_REMOTE_PATH="/opt/openshift-mcp-server"
   export MCP_REMOTE_KUBECONFIG="/path/to/remote/kubeconfig"
   export MCP_REMOTE_NODE_ENV="production"
   

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.

Phase 2: Remote MCP Server Setup

After configuring authentication, set up the MCP server on the bastion host:

Step 1: Initial Setup (Run Once)

Run the setup script to prepare the bastion host:

./scripts/setup-bastion.sh

This script will:

• ✅ Install Node.js and npm on the bastion host (if not present)
• ✅ Create the remote directory structure
• ✅ Copy project files to the bastion host
• ✅ Install all Node.js dependencies
• ✅ Verify dependency installation with import tests
• ✅ Test cluster connectivity and kubeconfig

Step 2: Test Connection

After successful setup, test the remote MCP server connection:

node simple-remote-launcher.js

This launcher will:

• Validate configuration and test connectivity
• Connect to the bastion host via SSH (key or password auth)
• Start the MCP server remotely with robust error handling
• Forward stdio for MCP protocol communication
• Enable AI Code Assistant integration with the remote cluster

Step 3: Configure AI Code Assistant

Update your AI Code Assistant MCP configuration to use the enhanced remote launcher:

{
  "mcpServers": {
    "openshift_mcp_server": {
      "command": "node",
      "args": ["/path/to/openshift-mcp-server/scripts/simple-remote-launcher.js"],
      "env": {
        "MCP_BASTION_HOST": "your-bastion-host.com",
        "MCP_BASTION_USER": "your-username",
        "MCP_SSH_KEY": "/path/to/your/ssh/key",
        "MCP_REMOTE_PATH": "/opt/openshift-mcp-server",
        "MCP_REMOTE_KUBECONFIG": "/path/to/remote/kubeconfig",
        "MCP_REMOTE_NODE_ENV": "production"
      },
      "cwd": "/path/to/openshift-mcp-server"
    }
  }
}

Troubleshooting Bastion Setup

Common Issues:

1. SSH Connection Failures

   • Verify SSH key permissions: chmod 600 ~/.ssh/id_rsa_bastion
   • Test manual SSH connection: ssh -i ~/.ssh/id_rsa_bastion user@bastion-host
   • Check network connectivity to bastion host

2. Node.js Installation Issues

   • Ensure bastion host has internet access for package downloads
   • Check if package manager (dnf/yum/apt) is available
   • Verify sudo permissions for Node.js installation

3. Dependency Installation Failures

   • Check npm registry accessibility from bastion host
   • Verify sufficient disk space in remote directory
   • Review npm install logs for specific errors

4. Kubeconfig Issues

   • Verify kubeconfig file exists at specified path
   • Test cluster connectivity from bastion host: kubectl cluster-info
   • Check network policies and firewall rules

Debug Mode:

export DEBUG=*
./scripts/setup-bastion.sh

Re-run Setup: If you need to re-run the setup (e.g., after fixing issues):

./scripts/setup-bastion.sh  # Safe to run multiple times

Installation

This MCP server can be deployed in two ways:

1. Local Direct Access: Run locally with direct cluster access
2. Remote Bastion Host Access: Run on a bastion host for private cluster access

Local Installation

npm install

Remote Installation

For remote bastion host deployment, follow the Bastion Host Setup section above.

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 Code Assistant

Once the MCP server is configured in your AI Code Assistant, 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:

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

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