MCP Server

Model Context Protocol server for AI-powered cluster management

The OpenShift Python Wrapper MCP Server provides powerful tools to interact with OpenShift/Kubernetes clusters using the Model Context Protocol (MCP). Integrate cluster management directly into AI assistants like Claude Desktop and Cursor.

Quick Start

Prerequisites

Python 3.8+

Required runtime environment

Cluster Access

OpenShift or Kubernetes cluster

Kubeconfig

Valid kubeconfig file

Installation

uv (Recommended)

uv tool install openshift-python-wrapper

Running the Server

# Run the MCP server
openshift-mcp-server

For development or running from source:

# Clone the repository
git clone https://github.com/RedHatQE/openshift-python-wrapper.git
cd openshift-python-wrapper

# Run directly
uv run mcp_server/server.py

Available Tools

The MCP server provides comprehensive tools for managing Kubernetes and OpenShift resources.

Resource Management

list_resources

List Kubernetes/OpenShift resources with filtering capabilities.

Parameters:

• resource_type (required): Type of resource (e.g., “pod”, “deployment”)
• namespace (optional): Namespace to search in
• label_selector (optional): Filter by labels (e.g., “app=nginx”)
• field_selector (optional): Filter by fields
• limit (optional): Maximum number of results

Basic Listing

# List all pods in the default namespace
list_resources(resource_type="pod", namespace="default")

get_resource

Get detailed information about a specific resource.

Parameters:

• resource_type (required): Type of resource
• name (required): Resource name
• namespace (optional): Namespace (required for namespaced resources)
• output_format (optional): Format - “info”, “yaml”, “json”, “wide” (default: “info”)

YAML Format

# Get pod details in YAML format
get_resource(
    resource_type="pod",
    name="nginx",
    namespace="default",
    output_format="yaml"
)

create_resource

Create a new resource from YAML or specifications.

Parameters:

• resource_type (required): Type of resource
• name (required): Resource name
• namespace (optional): Namespace for namespaced resources
• yaml_content (optional): Complete YAML definition
• spec (optional): Resource specification as dict
• labels (optional): Labels to apply
• annotations (optional): Annotations to apply
• wait (optional): Wait for resource to be ready

Simple Creation

# Create a namespace
create_resource(
    resource_type="namespace",
    name="test-ns",
    spec={}
)

update_resource

Update an existing resource using patch operations.

Parameters:

• resource_type (required): Type of resource
• name (required): Resource name
• namespace (optional): Namespace
• patch (required): Patch data as dict
• patch_type (optional): “merge”, “strategic”, “json” (default: “merge”)

# Scale a deployment
update_resource(
    resource_type="deployment",
    name="my-app",
    namespace="default",
    patch={"spec": {"replicas": 3}}
)

delete_resource

Delete a resource.

Parameters:

• resource_type (required): Type of resource
• name (required): Resource name
• namespace (optional): Namespace
• wait (optional): Wait for deletion to complete (default: true)
• timeout (optional): Deletion timeout in seconds (default: 60)

# Delete a pod
delete_resource(
    resource_type="pod",
    name="nginx",
    namespace="default"
)

apply_yaml

Apply YAML manifests containing one or more resources.

Parameters:

• yaml_content (required): YAML content with one or more resources
• namespace (optional): Default namespace for resources without namespace

yaml_content = """
---
apiVersion: v1
kind: Namespace
metadata:
  name: test-app
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
  namespace: test-app
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:latest
"""
apply_yaml(yaml_content=yaml_content)

Pod Operations

get_pod_logs

Retrieve logs from pod containers.

Parameters:

• name (required): Pod name
• namespace (required): Namespace
• container (optional): Container name (for multi-container pods)
• tail_lines (optional): Number of lines from end
• since_seconds (optional): Logs since N seconds ago
• previous (optional): Get logs from previous container instance

Tail Logs

# Get last 100 lines of logs
get_pod_logs(
    name="my-app-abc123",
    namespace="production",
    tail_lines=100
)

exec_in_pod

Execute commands inside pod containers.

Parameters:

• name (required): Pod name
• namespace (required): Namespace
• command (required): Command to execute as list
• container (optional): Container name

Config Check

# Check nginx config
exec_in_pod(
    name="nginx-pod",
    namespace="default",
    command=["nginx", "-t"]
)

Event and Discovery

get_resource_events

Get Kubernetes events related to a resource.

Parameters:

• resource_type (required): Type of resource
• name (required): Resource name
• namespace (optional): Namespace
• limit (optional): Maximum events to return (default: 10)

# Get pod events
get_resource_events(
    resource_type="pod",
    name="crashloop-pod",
    namespace="default"
)

get_resource_types

Get all available resource types in the cluster.

Parameters:

• random_string (required): Any string (required by MCP protocol)

# List all available resource types
get_resource_types(random_string="x")

AI Assistant Integration

Cursor Integration

Add to your Cursor settings (~/.cursor/mcp.json):

{
  "mcpServers": {
    "openshift-python-wrapper": {
      "command": "openshift-mcp-server"
    }
  }
}

Then use in Cursor with @openshift-python-wrapper.

Claude Desktop Integration

Add to Claude Desktop config:

Basic Configuration

{
  "mcpServers": {
    "openshift-python-wrapper": {
      "command": "openshift-mcp-server"
    }
  }
}

Custom Kubeconfig

{
  "mcpServers": {
    "openshift-python-wrapper": {
      "command": "openshift-mcp-server",
      "env": {
        "KUBECONFIG": "/home/user/.kube/config"
      }
    }
  }
}

Common Use Cases

Troubleshooting a Failing Pod

1. Check pod status

   pod = get_resource("pod", "failing-app", "production")
   
2. Get recent events

   events = get_resource_events("pod", "failing-app", "production")
   
3. Check logs

   logs = get_pod_logs("failing-app", "production", tail_lines=200)
   
4. Execute diagnostic command

   exec_in_pod(
       "failing-app",
       "production",
       ["cat", "/etc/app/config.yaml"]
   )
   

Deploying a Complete Application

# Apply all resources at once
yaml = """
---
apiVersion: v1
kind: Namespace
metadata:
  name: my-app
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: backend
  namespace: my-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: backend
  template:
    metadata:
      labels:
        app: backend
    spec:
      containers:
      - name: api
        image: myapp/backend:v1.0
        ports:
        - containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
  name: backend
  namespace: my-app
spec:
  selector:
    app: backend
  ports:
  - port: 80
    targetPort: 8080
"""
apply_yaml(yaml)

Checking Cluster Health

1. List nodes

   nodes = list_resources("node")
   
2. Check for pod issues

   problem_pods = list_resources(
       "pod",
       field_selector="status.phase!=Running,status.phase!=Succeeded"
   )
   
3. Review recent events

   events = list_resources("event", limit=50)
   

Managing OpenShift Virtualization

# Check CNV version
csv = list_resources(
    "clusterserviceversion",
    namespace="openshift-cnv"
)

# List VMs
vms = list_resources(
    "virtualmachine",
    namespace="my-vms"
)

# Check VM status
vm = get_resource(
    "virtualmachine",
    "rhel9-vm",
    "my-vms"
)

Supported Resource Types

The server dynamically discovers all available resource types from your cluster.

Core Kubernetes Resources

• pod, service, deployment, replicaset, daemonset
• configmap, secret, persistentvolume, persistentvolumeclaim
• namespace, node, event, endpoint
• serviceaccount, role, rolebinding, clusterrole, clusterrolebinding

OpenShift Specific

• route, project, imagestream, buildconfig, deploymentconfig
• user, group, oauth, securitycontextconstraints

OpenShift Virtualization

• virtualmachine, virtualmachineinstance, datavolume
• hyperconverged, kubevirt, cdi

Operators

• clusterserviceversion, subscription, installplan, operatorgroup
• catalogsource, packagemanifest

Security Best Practices

RBAC

Ensure your kubeconfig has appropriate permissions for operations

Namespaces

Use namespace isolation for multi-tenant environments

Resource Limits

Set appropriate limits when listing resources to avoid overload

Sensitive Data

Be careful with secrets and configmaps containing sensitive information

Troubleshooting

Connection Issues

Test cluster connectivity:

kubectl cluster-info
echo $KUBECONFIG
kubectl config current-context

Permission Errors

Check your permissions:

kubectl auth can-i --list

MCP Server Issues

Run in debug mode:

SIMPLE_LOGGER_LEVEL=DEBUG python mcp_server/server.py
tail -f /tmp/mcp_server_debug.log

Next Steps

API Reference

Explore the complete API documentation

Examples

Check out practical examples and tutorials