MCP Croit Ceph

AI-powered management for Croit Ceph clusters via the Model Context Protocol (MCP)

Connect your AI assistant (like Claude) directly to your Croit Ceph cluster for intelligent cluster management, troubleshooting, and monitoring.

What is this?

An MCP server that gives AI assistants access to your Croit Ceph cluster's REST API. Ask your AI to:

• "Show me all pools with errors"
• "List OSDs on server node-5"
• "Search logs for slow requests in the last hour"
• "What's the cluster health status?"

The AI can then interact with your cluster through natural language.

Key Features

🚀 Smart & Efficient

• Automatic token optimization - Responses optimized to save 80-95% on AI token costs
• Field selection - Request only the data you need (e.g., just id + name)
• Built-in filtering - grep-like search without multiple API calls
• Intelligent summaries - Large datasets get smart summaries with drill-down capability

🔍 Advanced Log Search

• Native VictoriaLogs integration for powerful log analysis
• Natural language queries: "Find OSD failures in the last 24 hours"
• Pattern detection and anomaly identification
• Pre-built debug templates for common issues

🛡️ Production Ready

• Role-based access control (ADMIN vs VIEWER)
• Automatic API discovery from your cluster
• Docker support with included OpenAPI spec
• Comprehensive error handling

Quick Start

Using Docker (Recommended)

docker run --rm -i \
  -e CROIT_HOST="https://your-cluster.com" \
  -e CROIT_API_TOKEN="your-api-token" \
  croit/mcp-croit-ceph:latest

With Claude Desktop

Add to ~/.config/claude/claude_desktop_config.json:

Basic configuration (fetches OpenAPI spec on startup):

{
  "mcpServers": {
    "croit-ceph": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "CROIT_HOST=http://your-cluster.croit.io:8080",
        "-e", "CROIT_API_TOKEN=your-api-token-here",
        "croit/mcp-croit-ceph:latest"
      ]
    }
  }
}

Optimized configuration (recommended - 2s startup instead of 5s):

{
  "mcpServers": {
    "croit-ceph": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/absolute/path/to/openapi.json:/config/openapi.json:ro",
        "-e", "CROIT_HOST=http://your-cluster.croit.io:8080",
        "-e", "CROIT_API_TOKEN=your-api-token-here",
        "-e", "OPENAPI_FILE=/config/openapi.json",
        "croit/mcp-croit-ceph:latest"
      ]
    }
  }
}

With debug logging:

{
  "mcpServers": {
    "croit-ceph": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "CROIT_HOST=http://your-cluster.croit.io:8080",
        "-e", "CROIT_API_TOKEN=your-api-token-here",
        "-e", "LOG_LEVEL=DEBUG",
        "croit/mcp-croit-ceph:latest"
      ]
    }
  }
}

Note: Volume mounts require absolute paths (not ~/). To download the OpenAPI spec:

curl -H "Authorization: Bearer YOUR_TOKEN" \
     http://your-cluster.croit.io:8080/api/swagger.json > openapi.json

Restart Claude Desktop after changing the configuration.

Configuration

Required Environment Variables

CROIT_HOST="https://your-cluster.com"      # Your Croit cluster URL
CROIT_API_TOKEN="your-api-token"           # API token from Croit

Optional Environment Variables

# Use local OpenAPI spec for faster startup (2s vs 5s)
OPENAPI_FILE="/config/openapi.json"

# Use bundled spec (no external fetch, for offline/dev)
USE_INCLUDED_API_SPEC="true"

# Logging verbosity: DEBUG, INFO, WARNING, ERROR
LOG_LEVEL="INFO"

# Pass additional CLI arguments
MCP_ARGS="--no-permission-check --max-category-tools 5"

See .env.example for docker usage template.

Getting an API Token

1. Log into your Croit cluster web interface
2. Go to Settings → API Tokens
3. Create a new token with appropriate permissions
4. Copy the token and use it in your configu

... View full README on GitHub