OpenShift MCP Server

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 20+
• 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.