OpenShift MCP Server

OpenShift MCP Server

[CI Pipeline] [CodeQL] [License: MIT] [Node.js Version] [TypeScript] [OpenShift] [Kubernetes] [MCP] [Test Coverage] [Tests] [npm version] [npm downloads] [Docker] [PRs Welcome] [Maintenance]

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.gitcd mcp-server-openshiftnpm installnpm 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 servernpm run start:http
# Connect via MCP remotenpx -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/passwordoc_login with server: "https://api.cluster.example.com:6443",         authMethod: "password",         username: "developer",         password: "your-password"

Discover API Resources

# List all available API resourcesoc_api_resources
# List resources for specific API groupoc_api_resources with apiGroup: "apps"
# List only namespaced resourcesoc_api_resources with namespaced: true
# Explain a resource schemaoc_explain with resource: "deployment"
# Explain specific fieldoc_explain with resource: "pod", field: "spec.containers"

Deploy Application

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

Scale Application

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

Patch Resource

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

Troubleshoot Issues

# Get pod troubleshooting guidanceUse prompt: troubleshoot-openshift-promptArguments: issueType: "pod", resourceName: "my-app-12345", namespace: "my-project"
# Get deployment troubleshooting guidanceUse prompt: troubleshoot-openshift-promptArguments: issueType: "deployment", resourceName: "my-app", namespace: "my-project"
# Get general cluster troubleshooting guidanceUse prompt: troubleshoot-openshift-promptArguments: issueType: "cluster", symptoms: "nodes not ready"

Development

# Setupnpm install
# Buildnpm run build
# Testnpm test
# Start (STDIO)npm start
# Start (HTTP)npm run start:http
# Development modenpm 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.