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): ``json { "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): ``json { "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: ``json { "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: ``bash 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

Log into your Croit cluster web interface
Go to Settings → API Tokens
Create a new token with appropriate permissions
Copy the token and use it in your configuration

Example AI Conversations

Check cluster health: `` You: "What's the current cluster status?" AI: Calls list_endpoints → Finds status endpoint → Returns health summary ``

Find problems: `` You: "Show me all pools with errors" AI: Calls /pools with fields=["id","name","status"] and filter for errors Returns only the 3 pools with issues (instead of all 100 pools) ``

Debug issues: `` You: "Search logs for OSD failures in the last hour" AI: Uses croit_log_search with smart query parsing Returns summary + drill-down capability for details ``

Capacity planning: `` You: "Which pools are over 80% full?" AI: Gets pools → Filters by usage → Returns list with recommendations ``

Features in Detail

Token Optimization

The server automatically reduces AI token consumption:

| Without Optimization | With Optimization | Savings | |---------------------|-------------------|---------| | 100 pools, all fields → 4,000 tokens | 100 pools, id+name → 300 tokens | 92% | | 500 OSDs, full data → 15,000 tokens | Smart summary → 1,000 tokens | 93% |

How it works:

Field Selection: Request only needed fields
Smart Summaries: Large datasets get summaries with drill-down
Caching: Repeated requests use cached data
Auto-limiting: Sensible defaults prevent token explosions

Available Tools

The AI has access to these tools:

Core Tools:

list_endpoints - Discover available API endpoints
call_endpoint - Make API calls with optimization
search_last_result - Drill down into large responses

Category Tools (auto-generated):

manage_services - Ceph services
manage_pools - Storage pools
manage_servers - Cluster servers
manage_s3 - S3 buckets
And more...

Log Search:

croit_log_search - Advanced log analysis
croit_log_check - Quick log condition checks

Advanced Usage

Local Development

# Clone repository
git clone https://github.com/croit/mcp-croit-ceph.git
cd mcp-croit-ceph

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run directly
export CROIT_HOST="https://your-cluster.com"
export CROIT_API_TOKEN="your-token"
python mcp-croit-ceph.py

Using Local OpenAPI Spec

For faster startup or offline development:

# Download spec from your cluster
curl -H "Authorization: Bearer $CROIT_API_TOKEN" \
     https://your-cluster/api/swagger.json > openapi.json

# Use local spec
python mcp-croit-ceph.py --openapi-file openapi.json

Command Line Options

python mcp-croit-ceph.py \
  --openapi-file openapi.json \      # Use local OpenAPI spec
  --no-permission-check \            # Skip role check (faster)
  --max-category-tools 5             # Limit category tools

Permissions & Security

The server respects your API token's role:

ADMIN: Full access to all operations
VIEWER: Read-only access (no create/delete/update)
Invalid token: Server exits with error

Admin-only categories: maintenance, servers, config, hooks

Troubleshooting

Token not working:

Verify token in Croit web interface
Check token hasn't expired
Ensure token has correct permissions

Connection issues:

Verify CROIT_HOST is correct (include https://)
Check network connectivity to cluster
Verify firewall allows connection

No tools showing:

Check Docker logs for errors
Verify OpenAPI spec is valid
Try --no-permission-check to test

Enable debug logging: ``bash export LOG_LEVEL=DEBUG python mcp-croit-ceph.py ``

Documentation

Architecture - Technical architecture and design
Token Optimization - How optimization works
Claude Integration - Tips for using with Claude

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Run black formatter on Python files
Submit a pull request

License

See LICENSE for details

Support

Issues: GitHub Issues
Croit Support: For cluster-specific questions
MCP Protocol: Model Context Protocol Documentation

---

Made with ❤️ for the Ceph community

mcp-croit-ceph