Minimum Requirements: MCC 2.28+ | MOSK Platform 25.1+ | Python 3.11+

An MCP (Model Context Protocol) server that enables AI assistants like Claude to manage Mirantis OpenStack for Kubernetes (MOSK) clusters through natural conversation. Query cluster health, troubleshoot issues, generate infrastructure templates, and perform operations - all by simply asking.

Version: 0.1.0 | Tools: 81 | Categories: 11

⚠️ Prerequisite: Before using the MCP server, enable OAuth 2.0 Device Authorization Grant on your MCC Keycloak kaas and k8s clients. See Keycloak Configuration for steps.

This is the simplest way to get started. Docker handles all dependencies.

Step 1: Create cluster configuration

Create ~/.config/mosk-mcp/clusters.yaml:

config_version: '1.0'
active: lab
clusters:
  lab:
    url: https://172.16.166.22
    name: LAB
    description: Local development/lab cluster
    environment: development
    ssl_verify: false
  production:
    url: https://mcc.example.com
    name: Production
    description: Production MCC cluster
    environment: production
    ssl_verify: true
confirm_production_switch: true
allow_http_clusters: true

Step 2: Configure Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "mosk-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "~/.config/mosk-mcp:/home/mosk-mcp/.config/mosk-mcp:rw",
        "-e", "MCP_TRANSPORT=stdio",
        "-e", "MCP_METRICS_ENABLED=false",
        "-e", "MCP_AUTH_ENABLED=true",
        "reddydodda/mosk-mcp:latest"
      ]
    }
  }
}

Note: On macOS, replace ~ with full path: /Users/YOUR_USERNAME/.config/mosk-mcp

Step 3: Restart Claude Desktop and authenticate

You: "Log me in"
Claude: [Opens browser for secure authentication]
        Complete login in your browser...

You: "What's the cluster health?"
Claude: Overall health: 94% (Healthy)
        - Kubernetes: 98% (All nodes ready)
        - OpenStack: 92% (2 minor alerts)
        - Ceph: 95% (HEALTH_OK)

Step 1: Build the image

git clone https://github.com/Mirantis/mosk-mcp.git
cd mosk-mcp
./scripts/docker-build.sh --local

Step 2: Create cluster config and Claude Desktop config

Same as Option 1, but use your local image name instead of reddydodda/mosk-mcp:latest.

Step 1: Install the package

git clone https://github.com/Mirantis/mosk-mcp.git
cd mosk-mcp
pip install -e .

Step 2: Create cluster configuration

Create ~/.config/mosk-mcp/clusters.yaml (same as Option 1).

Step 3: Configure Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mosk-mcp": {
      "command": "python3",
      "args": ["-m", "mosk_mcp"],
      "env": {
        "PYTHONPATH": "/path/to/mosk-mcp/src",
        "MCP_TRANSPORT": "stdio",
        "MCP_AUTH_ENABLED": "true"
      }
    }
  }
}

claude mcp add mosk-mcp \
  -e MCP_TRANSPORT=stdio \
  -e MCP_AUTH_ENABLED=true \
  -- python3 -m mosk_mcp

Secure OAuth 2.0 Device Flow authentication - no passwords in chat.

Manage multiple MCC clusters safely.

Generate infrastructure-as-code templates without applying them.

Monitor distributed storage health and capacity.

Monitor OpenStack message queues.

Manage bare metal servers and Kubernetes nodes.

Monitor deployments, upgrades, and platform operations.

Unified health across all components.

Diagnose issues and find solutions.

Test and validate cluster functionality.

Server health and diagnostics.

1. generate_node_templates() → Create BMHi + BMHp + Machine templates
2. validate_template() → Validate all templates
3. apply_machine(crq=CRQ...) → Provision the node
4. get_node_provision_progress() → Track BMHi→BMH→Machine→Node
5. get_node_readiness() → Verify node is ready

1. list_available_releases() → See available MOSK versions
2. run_preflight_check(type=upgrade) → Validate readiness
3. apply_cluster_release_patch(crq=CRQ...) → Change version
4. get_mosk_platform_upgrade_progress() → Track upgrade
5. run_mosk_platform_validation() → Validate post-upgrade

1. get_openstack_deployment_status() → Check current state
2. apply_osdpl_patch(crq=CRQ...) → Change OpenStack version
3. get_openstack_upgrade_progress() → Track per-component progress
4. run_post_upgrade_validation() → Smoke tests and validation

1. list_active_alerts() → Find current issues
2. get_alert_details() → Understand what's wrong
3. query_logs() → Search relevant logs
4. correlate_events() → Find related issues
5. diagnose_vm_failure() / diagnose_network_issue() → Specific diagnosis
6. suggest_resolution() → Get AI-powered fixes

1. get_node_readiness(check_type=maintenance) → Verify safe to maintain
2. create_maintenance_request() → Generate maintenance CR
3. get_migration_status() → Track VM migrations off node
4. list_maintenance_requests() → Monitor maintenance status

Server options are loaded from defaults, optional .env, process environment variables, and (when you run the mosk-mcp / python -m mosk_mcp entrypoint) command-line flags. Field names map to env vars with the MCP_ prefix (see Settings in src/mosk_mcp/core/config.py).

DOTENV_PATH is intentionally not MCP_-prefixed: it selects which file is merged before other sources (default: .env in the current working directory when the process starts).

When using the mosk-mcp console script (or python -m mosk_mcp), explicit CLI flags override environment variables, which override values from .env, which override built-in defaults. Run mosk-mcp --help for the full list of flags (pydantic-settings builds them from the settings model; options use kebab-case, e.g. --log-level).

Common flags and shortcuts (equivalent env vars in parentheses):

All settings from src/mosk_mcp/core/config.py can be configured via environment variables using MCP_<FIELD_NAME> (for example, transport -> MCP_TRANSPORT).

MCP_CONFIG_PATH and MCP_PROFILE are optional and mainly used for multi-cluster mode via clusters.yaml; single-cluster workflows can use MCP_MCC_URL directly.

Automatic data redaction for tool outputs before they are sent to the LLM.

The MOSK MCP Server uses OAuth 2.0 Device Authorization Flow for secure browser-based authentication. This requires enabling a single setting on two MCC Keycloak clients.

Step 1: Access Keycloak Admin Console

https://<mcc-url>/auth/admin/

Login with Keycloak admin credentials.

Step 2: Enable Device Flow on kaas Client

1. Select the iam realm
2. Go to Clients → Select kaas
3. In Settings tab, find Capability config section
4. Enable ✅ OAuth 2.0 Device Authorization Grant
5. Click Save

Step 3: Enable Device Flow on k8s Client

1. Go to Clients → Select k8s
2. In Settings tab, find Capability config section
3. Enable ✅ OAuth 2.0 Device Authorization Grant
4. Click Save

Note: Both clients must have this setting enabled for full MCC/MOSK authentication support.

Step 4: Verify Configuration

Test the device authorization endpoint:

curl -k https://<mcc-url>/auth/realms/iam/protocol/openid-connect/auth/device

A successful response returns JSON (not a 404 error).

Default MCC Keycloak settings:

• Access token: 5 minutes
• Refresh token: 30 minutes

The MCP server automatically handles token refresh.

Manage multiple MCC clusters with safe switching.

Create ~/.config/mosk-mcp/clusters.yaml:

config_version: '1.0'
active: lab
confirm_production_switch: true
allow_http_clusters: true

clusters:
  lab:
    url: https://172.16.166.22
    name: LAB
    description: Local development/lab cluster
    environment: development
    ssl_verify: false
    is_locked: false

  production-us:
    url: https://mcc-us.example.com
    name: Production US
    description: US production MCC cluster
    environment: production
    ssl_verify: true
    is_locked: false

  production-eu:
    url: https://mcc-eu.example.com
    name: Production EU
    description: EU production MCC cluster
    environment: production
    ssl_verify: true
    is_locked: false

You: "List my clusters"
Claude: You have 3 configured clusters:
        - lab (active, development)
        - production-us (production)
        - production-eu (production)

You: "Switch to production-us"
Claude: Switching from lab to production-us.
        This is a PRODUCTION cluster. Session will be cleared.
        Confirm switch? [Yes/No]

Operations that modify cluster state require a Change Request (CRQ) number for audit compliance.

CRQ followed by 9 digits: CRQ123456789

All privileged operations default to dry-run mode. Pass dry_run=false to execute.

Claude Desktop manages the container lifecycle automatically. Configure via claude_desktop_config.json:

{
  "mcpServers": {
    "mosk-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/YOUR_USERNAME/.config/mosk-mcp:/home/mosk-mcp/.config/mosk-mcp:rw",
        "-e", "MCP_TRANSPORT=stdio",
        "-e", "MCP_METRICS_ENABLED=false",
        "-e", "MCP_AUTH_ENABLED=true",
        "reddydodda/mosk-mcp:latest"
      ]
    }
  }
}

# Build local image
./scripts/docker-build.sh --local

# Start in HTTP mode for testing
./scripts/docker-run.sh start --mcc-url https://mcc.example.com

# Status, logs, stop
./scripts/docker-run.sh status
./scripts/docker-run.sh logs -f
./scripts/docker-run.sh stop

┌─────────────────┐     ┌─────────────────┐
│   Claude/MCP    │     │    Keycloak     │
│     Client      │────▶│   (OIDC Auth)   │
└────────┬────────┘     └─────────────────┘
         │
         ▼
┌─────────────────┐
│  MOSK MCP       │
│  Server         │
└────────┬────────┘
         │
    ┌────┴────┐
    ▼         ▼
┌───────┐ ┌───────┐
│  MCC  │ │ MOSK  │
│Cluster│ │Cluster│
└───────┘ └───────┘

MCC (Management Cluster): Runs LCM controllers, hosts Machine/BMHi/BMHp CRs MOSK (Workload Cluster): Runs OpenStack services, hosts OSDPL, Ceph

# CLI and env (local install)
mosk-mcp --help

# Run tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=mosk_mcp

# Code quality
ruff format src tests
ruff check src tests
mypy src

Connection refused:

curl -k https://your-mcc-url/config.js

SSL certificate errors:

export MCP_SSL_VERIFY=false

Authentication failures:

You: "Check session status"
You: "Log me in"  # If not authenticated

• OSD removal tools deferred to future release
• Machine deletion tool deferred to future release
• Upgrade rollback not supported through MCP tools

Apache License 2.0