Ceph

You can run a Python-based MCP server that exposes Ceph cluster health, host status, and health details to AI assistants. This server provides a structured, secure bridge between your Ceph Manager API and downstream AI tools, enabling natural-language queries to manage and troubleshoot your storage infrastructure.

How to use

To use this MCP server, you run it locally or on a host where you can reach your Ceph Manager API. Start the server with a simple command, then query it through an MCP client to retrieve cluster health, host information, and detailed health checks. The server formats responses in a way that AI assistants can interpret clearly, making it easy to embed storage insights into conversations and automated flows.

How to install

Prerequisites set you up for a smooth installation. You need Python 3.11 or higher, the UV project tooling, access to a Ceph cluster with the Manager API enabled, and valid Ceph credentials with appropriate permissions.

Step 1. Create the project directory and initialize UV for Python 3.11.

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

# Initialize UV project
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

Step 2. Set up your environment by copying the example file and editing it with your Ceph details.

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

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

Step 3. Configure your Ceph connection inside the environment file.

# .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

Additional configuration and considerations

Environment variables from the configuration guide control how the MCP server connects to Ceph and how verbose its logging is. Adjust these for development or production use.

Security notes to consider before going to production include enabling SSL verification, storing credentials securely, ensuring network reachability to the Ceph Manager API, and using a dedicated Ceph user with minimal required permissions.

Start the server when you are ready to test it locally.

uv run python -m ceph_mcp.server

Security and reliability notes

Production usage requires enabling SSL verification and managing credentials securely. Ensure the MCP server can reach the Ceph Manager API endpoint and that the Ceph user has appropriate read permissions for health and host information.

Troubleshooting tips

If you encounter connection issues, verify the Ceph Manager is running, confirm the URL and port, and check networking between the MCP server and the Ceph cluster. If authentication fails, recheck the Ceph username and password and ensure the user has active permissions.

Development and testing

Use the provided commands to run tests, format code, and run the linter. Tests help ensure that health checks and host information are reliably returned to clients.

Available tools

get_cluster_health

Fetches the overall cluster health, warnings, and statistics to give you a quick health snapshot of the Ceph cluster.

get_host_status

Returns the online/offline status of hosts in the cluster and the distribution of services across hosts.

get_health_details

Provides detailed health checks and warnings to help troubleshoot specific issues.

get_host_details

Gives comprehensive information about a specific host, including running services and hardware details.