ceph

This MCP server provides a bridge between AI assistants and a Ceph storage cluster, exposing four main tools to inspect and troubleshoot the cluster via natural language prompts. You can query cluster health, per-host status, detailed health checks, and specific host information. The tools are designed to return AI-friendly, structured responses that summarize status, warnings, and key metrics, enabling seamless integration into conversational assistants. To interact with the server, run it using Python's module interface and then invoke the available tools through your MCP client or AI agent that supports MCP calls. The four tools are: get_cluster_health, get_host_status, get_health_details, and get_host_details (with a hostname parameter for the last one). Use these tools to answer questions like “How is my Ceph cluster doing?”, “Which hosts are online?”, “What specific warnings exist?”, or “What services are running on host ceph-node-01?”. The server authenticates to the Ceph Manager API and returns concise, actionable results suitable for driving AI-driven workflows.

Prerequisites:

• Python 3.11 or higher
• UV project manager
• Access to a Ceph cluster with Manager API enabled
• Valid Ceph credentials with appropriate permissions

Installation steps:

1. Clone and set up the project

# Create the project directory
mkdir ceph-mcp-server
cd ceph-mcp-server

# Initialize UV project (Python 3.11)
uv init --python 3.11

# Add dependencies
uv add mcp httpx pydantic python-dotenv structlog asyncio-mqtt
uv add --dev pytest pytest-asyncio black isort mypy ruff

2. Set up your environment

# Copy the example environment file
cp .env.example .env

# Edit .env with your Ceph cluster details
nano .env

3. Configure Ceph connection in environment (example)

# .env file contents
CEPH_MANAGER_URL=https://192.16.0.31:8443
CEPH_USERNAME=admin
CEPH_PASSWORD=your_ceph_password
CEPH_SSL_VERIFY=false  # Set to true in production with proper certificates

4. Run the MCP server

uv run python -m ceph_mcp.server

Environment variables customize how the MCP server connects to Ceph. Ensure CEPH_MANAGER_URL, CEPH_USERNAME, and CEPH_PASSWORD are kept secure and not committed to version control. In development, you can disable SSL verification with CEPH_SSL_VERIFY=false, but in production always enable SSL verification and consider providing CEPH_CERT_PATH for trusted certificates. If you encounter connection or authentication issues, verify network access to the Ceph Manager API and that the Ceph user has the necessary permissions. The server is designed for asynchronous operation to handle multiple requests efficiently. You can adjust logging with LOG_LEVEL to DEBUG during troubleshooting.