mcp-server-openshift

OpenShift MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with comprehensive OpenShift/Kubernetes cluster management capabilities through the oc command-line interface.

Demo Video

Watch the oc-new-app tool deploy a complete Spring Boot application from GitHub to OpenShift:

https://github.com/user-attachments/assets/f4bace3f-755b-462f-8a8a-680e4dc02129

Features

• Cluster Information: Access comprehensive cluster status, nodes and configuration via MCP resources
• Resource Description: Describe any resource with multiple output formats including human-readable summaries
• Complete Resource Management: Create, read, update, delete, and patch all OpenShift/Kubernetes resources
• Application Deployment: Deploy applications from Git repositories with S2I builds and automatic route creation
• Operator Management: Install operators via OLM, Helm, or direct manifests
• Cluster Operations: Scaling, monitoring, troubleshooting and management
• Build Operations: Start and monitor OpenShift builds
• Scaling Operations: Scale deployments, replicasets and statefulsets
• Logging: Retrieve logs from pods and builds
• Multi-Transport Support: STDIO and HTTP/SSE transports for different integration scenarios
• Comprehensive Testing: 99 unit tests ensuring production reliability
• Rich Error Handling: Detailed troubleshooting guidance and actionable error messages
• Troubleshooting Prompts: Interactive troubleshooting guides for common OpenShift scenarios
• Log Sampling: Sample and analyze pod logs with intelligent pattern detection and context

Prerequisites

• Node.js 18+
• OpenShift CLI (oc) installed and configured
• Access to an OpenShift cluster

Installation

git clone https://github.com/sanjaypsachdev/mcp-server-openshift.git
cd mcp-server-openshift
npm install
npm run build

Configuration

Add to your MCP client configuration:

Claude Desktop / Cursor

{
  "mcpServers": {
    "openshift": {
      "command": "node",
      "args": ["/path/to/mcp-server-openshift/dist/index.js"],
      "env": {
        "OPENSHIFT_CONTEXT": "your-context-name",
        "OPENSHIFT_NAMESPACE": "your-default-namespace"
      }
    }
  }
}

HTTP/SSE Transport (Remote Access)

# Start HTTP server
npm run start:http

# Connect via MCP remote
npx -y mcp-remote http://localhost:3000/sse --transport sse-only

Tools

Authentication & Access

• oc_login - Securely log into OpenShift clusters using token or username/password authentication

API Discovery & Documentation

• oc_api_resources - List all available API resources in the cluster with categorization
• oc_explain - Explain resource schemas, fields, and API documentation

Core Resource Management

• oc_get - Get OpenShift resources (pods, deployments, services, routes, etc.)
• oc_create - Create OpenShift resources from manifests or templates
• oc_apply - Apply YAML manifests with validation and conflict resolution
• oc_delete - Delete resources with safety checks and confirmation options
• oc_patch - Patch resources using strategic merge, JSON merge, or JSON patch operations
• oc_describe - Describe resources with multiple output formats

Application Lifecycle

• oc_new_app - Deploy applications from Git repositories with S2I builds
• oc_scale - Scale deployments, deploymentconfigs, replicasets, and statefulsets
• oc_logs - Get logs from pods, deployments, builds with filtering options

Advanced Operations

• oc_install_operator - Install operators via OLM, Helm, or direct manifests

Resources

MCP Resources provide read-only access to cluster information:

• openshift://cluster-info - Comprehensive cluster status, nodes, namespaces, and events
• openshift://project-list - Detailed project information with quotas and usage statistics
• openshift://app-templates - Application deployment templates and patterns

Prompts

Interactive troubleshooting and operational guidance:

• troubleshoot-openshift-prompt - Comprehensive OpenShift troubleshooting guide for all resource types and cluster issues
• monitoring-prompts - Monitoring and observability guidance for different scenarios

Sampling

Intelligent log analysis and pattern detection:

• Pod Logs Sampling - Automatic log sampling with error pattern detection and context analysis

Usage Examples

Login to Cluster

# Login with token (recommended)
oc_login with server: "https://api.cluster.example.com:6443",
         authMethod: "token",
         token: "sha256~your-token-here"

# Login with username/password
oc_login with server: "https://api.cluster.example.com:6443",
         authMethod: "password",
         username: "developer",
         password: "your-password"

Discover API Resources

# List all available API resources
oc_api_resources

# List resources for specific API group
oc_api_resources with apiGroup: "apps"

# List only namespaced resources
oc_api_resources with namespaced: true

# Explain a resource schema
oc_explain with resource: "deployment"

# Explain specific field
oc_explain with resource: "pod", field: "spec.containers"

Deploy Application

# Deploy Node.js app from GitHub
oc_new_app with gitRepo: "https://github.com/sclorg/nodejs-ex.git"

Scale Application

# Scale deployment to 3 replicas
oc_scale with name: "my-app", replicas: 3

Patch Resource

# Update deployment labels
oc_patch with resourceType: "deployment", name: "my-app",
         patch: '{"metadata":{"labels":{"environment":"production"}}}'

Troubleshoot Issues

# Get pod troubleshooting guidance
Use prompt: troubleshoot-openshift-prompt
Arguments: issueType: "pod", resourceName: "my-app-12345", namespace: "my-project"

# Get deployment troubleshooting guidance
Use prompt: troubleshoot-openshift-prompt
Arguments: issueType: "deployment", resourceName: "my-app", namespace: "my-project"

# Get general cluster troubleshooting guidance
Use prompt: troubleshoot-openshift-prompt
Arguments: issueType: "cluster", symptoms: "nodes not ready"

Development

# Setup
npm install

# Build
npm run build

# Test
npm test

# Start (STDIO)
npm start

# Start (HTTP)
npm run start:http

# Development mode
npm run dev

Transport Modes

STDIO (Default)

• Direct MCP client integration
• Lower latency
• Recommended for local development

HTTP/SSE

• Remote access capability
• Web integration friendly
• Container deployment ready

Architecture

src/
├── index.ts              # Main server entry point
├── tools/                # Tool implementations
├── resources/            # MCP resources
├── prompts/              # Interactive prompts
├── sampling/             # Log sampling and analysis
├── models/               # Zod validation schemas
└── utils/                # OpenShift CLI wrapper

Security

Authentication Security

• Token Authentication: Preferred method for automation and production use
• Password Authentication: Available but token authentication is recommended
• HTTPS Enforcement: All cluster connections must use HTTPS
• URL Validation: Server URLs validated to prevent SSRF attacks
• Private IP Blocking: Prevents connections to internal/metadata services

Operational Security

• RBAC Compliance: Respects OpenShift RBAC permissions
• No Credential Storage: Credentials are not stored or transmitted by the server
• User Permissions: Executes with the same permissions as the authenticated user
• Input Validation: Comprehensive validation of all inputs and parameters
• Secure Defaults: Conservative security settings by default

Best Practices

• Use Service Account Tokens: For automation and CI/CD pipelines
• Regular Token Rotation: Rotate authentication tokens regularly
• TLS Certificate Validation: Always validate TLS certificates in production
• Least Privilege: Use accounts with minimal required permissions
• Session Management: Use oc logout to clear credentials when done

License

MIT License - see LICENSE file for details.