thoraxe/ols-mcp

OpenShift LightSpeed MCP Server

A Model Context Protocol (MCP) server that integrates OpenShift LightSpeed capabilities with Claude Code, enabling AI-powered OpenShift assistance and troubleshooting.

Overview

This MCP server provides Claude Code with access to OpenShift LightSpeed, allowing users to get expert OpenShift guidance, troubleshooting help, and best practices directly within their development workflow.

Features

• OpenShift Expertise: Get answers to OpenShift-related questions and troubleshooting guidance
• Seamless Integration: Works directly within Claude Code for enhanced development experience
• Configurable: Flexible configuration for different OpenShift LightSpeed deployments
• Error Handling: Robust error handling and timeout management

Installation

Prerequisites

• Python 3.12+
• uv package manager
• Access to an OpenShift LightSpeed API endpoint

Setup

1. Clone and install dependencies:

   cd ols-mcp
   uv sync
   

2. Configure environment:

   cp .env.example .env
   # Edit .env with your OLS API configuration
   

3. Test the server:

   uv run python -m ols_mcp.server
   

Configuration

Environment Variables

Configure the server using environment variables or a .env file:

Example .env file:

OLS_API_URL=https://your-ols-instance.com
OLS_API_TOKEN=your-bearer-token-here
OLS_TIMEOUT=30.0
OLS_VERIFY_SSL=true

Claude Code Integration

To use this MCP server with Claude Code, add it to your Claude Code configuration:

Configuration File Location

• Linux/macOS: ~/.config/claude-code/config.json
• Windows: %APPDATA%\claude-code\config.json

Configuration Example

Add the following to your config.json:

{
  "mcpServers": {
    "openshift-lightspeed": {
      "command": "uv",
      "args": ["run", "python", "-m", "ols_mcp.server"],
      "cwd": "/path/to/your/ols-mcp",
      "env": {
        "OLS_API_URL": "https://your-ols-instance.com",
        "OLS_API_TOKEN": "your-token-here",
        "OLS_TIMEOUT": "30.0",
        "OLS_VERIFY_SSL": "true"
      }
    }
  }
}

Important: Update the cwd path to point to your actual ols-mcp directory.

Verification

1. Restart Claude Code after adding the configuration
2. The openshift-lightspeed tool should now be available
3. Test with OpenShift-related questions

Usage Examples

Once integrated with Claude Code, you can ask questions like:

• "Help me troubleshoot a pod that's failing to start"
• "How do I scale a deployment in OpenShift?"
• "My application is getting 503 errors, what should I check?"
• "Show me how to create a route for my service"
• "What's the best way to configure resource limits?"

Claude Code will automatically use the OpenShift LightSpeed MCP server to provide expert OpenShift guidance.

Development

Project Structure

ols-mcp/
├── pyproject.toml              # uv project configuration
├── .env.example               # Environment configuration template
├── src/ols_mcp/
│   ├── __init__.py
│   ├── models.py              # Pydantic models for requests/responses
│   ├── client.py              # HTTP client for OLS API communication
│   └── server.py              # MCP server implementation
└── README.md                  # This file

Available Tools

The server provides the following MCP tool:

• openshift-lightspeed: Submit queries to OpenShift LightSpeed and receive expert guidance

Error Handling

The server includes comprehensive error handling for:

• Network connectivity issues
• API authentication failures
• Timeout scenarios
• Invalid responses
• SSL certificate problems

Troubleshooting

Common Issues

1. Connection Refused: Check that OLS_API_URL is correct and the service is running
2. Authentication Errors: Verify your OLS_API_TOKEN is valid and has proper permissions
3. SSL Errors: For self-signed certificates, set OLS_VERIFY_SSL=false
4. Timeout Issues: Increase OLS_TIMEOUT for slower networks

Debug Mode

Run the server with debug logging:

DEBUG=1 uv run python -m ols_mcp.server

Contributing

This project uses:

• uv for dependency management
• Pydantic for data validation
• httpx for HTTP client functionality
• MCP SDK for protocol implementation

License

This project is part of the OpenShift ecosystem and follows Red Hat's open source practices.