What is Ceph Mcp Server

Ceph MCP Server is a Model Context Protocol (MCP) server that allows AI assistants to interact with Ceph storage clusters using natural language. It serves as a bridge between AI tools and Ceph infrastructure, simplifying storage management.

Use cases

Use cases include monitoring the health of Ceph clusters, managing storage resources through AI assistants, troubleshooting issues with detailed diagnostics, and integrating storage management into AI workflows.

How to use

To use Ceph MCP Server, clone the project repository, set up the environment with the required dependencies, configure your Ceph connection in the .env file, and start the server using the command ‘uv run python -m ceph_mcp.server’.

Key features

Key features include health monitoring of the cluster, host management, detailed analysis for troubleshooting, secure communication with authenticated access to the Ceph Manager API, structured responses for AI, and an asynchronous architecture for improved performance.

Where to use

Ceph MCP Server can be used in various fields such as cloud storage management, data center operations, AI-driven data analytics, and any environment that requires efficient management of Ceph storage clusters.

Ceph MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to interact with Ceph storage clusters through natural language. This server provides a bridge between AI tools and your Ceph infrastructure, making storage management more accessible and intuitive.

🚀 Features

• Health Monitoring: Get comprehensive cluster health status and diagnostics
• Host Management: Monitor and manage cluster hosts and their services
• Detailed Analysis: Access detailed health checks for troubleshooting
• Secure Communication: Authenticated access to Ceph Manager API
• Structured Responses: AI-friendly output formatting for clear communication
• Async Architecture: Non-blocking operations for better performance

📋 Prerequisites

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

🛠️ Installation

1. Clone and setup the project:

# 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

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 your Ceph connection:

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

🏃‍♂️ Quick Start

1. Start the MCP server:

uv run python -m ceph_mcp.server

2. Test the connection:
   The server will log its startup and any connection issues. Look for messages indicating successful connection to your Ceph cluster.

🔧 Configuration

Environment Variables

Variable	Description	Default	Required
CEPH_MANAGER_URL	Ceph Manager API endpoint	https://192.16.0.31:8443	Yes
CEPH_USERNAME	Ceph username for API access	admin	Yes
CEPH_PASSWORD	Ceph password for authentication	-	Yes
CEPH_SSL_VERIFY	Enable SSL certificate verification	true	No
CEPH_CERT_PATH	Path to custom SSL certificate	-	No
LOG_LEVEL	Logging level (DEBUG, INFO, WARNING, ERROR)	INFO	No
MAX_REQUESTS_PER_MINUTE	Rate limiting for API requests	60	No

Security Considerations

• Production Usage: Always enable SSL verification (CEPH_SSL_VERIFY=true) in production
• Credentials: Store credentials securely and never commit them to version control
• Network Access: Ensure the MCP server can reach your Ceph Manager API endpoint
• Permissions: Use a dedicated Ceph user with minimal required permissions

🎯 Available Tools

The MCP server provides four main tools for AI assistants:

1. get_cluster_health

Get comprehensive cluster health status including overall health, warnings, and statistics.

Use cases:

• “How is my Ceph cluster doing?”
• “Are there any storage issues I should know about?”
• “What’s the current status of my cluster?”

2. get_host_status

Retrieve information about all hosts in the cluster including online/offline status and service distribution.

Use cases:

• “Which hosts are online in my cluster?”
• “What services are running on each host?”
• “Are any hosts having problems?”

3. get_health_details

Get detailed health check information for troubleshooting specific issues.

Use cases:

• “What specific warnings does my cluster have?”
• “Give me detailed information about cluster errors”
• “Help me troubleshoot this storage issue”

4. get_host_details

Get comprehensive information about a specific host.

Parameters:

• hostname: The name of the host to examine

Use cases:

• “Tell me about host ceph-node-01”
• “What services are running on this specific host?”
• “Get detailed specs for this host”

📊 Example Interactions

Health Check

AI Assistant: "How is my Ceph cluster doing?"

Response: ✅ Cluster is healthy. All 3 hosts are online. OSDs: 12/12 up.
🟢 Overall Status: HEALTH_OK
🖥️  Hosts: 3/3 online
💾 OSDs: 12/12 up

Troubleshooting

AI Assistant: "What warnings does my cluster have?"

Response: 🟡 Cluster has 2 warning(s) requiring attention.
🟡 Warnings requiring attention:
   - OSD_NEARFULL: 1 osd(s) are getting full
   - POOL_BACKFILLFULL: 1 pool(s) are backfill full

🧪 Development

Running Tests

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=ceph_mcp

# Run specific test types
uv run pytest -m "not integration"  # Skip integration tests

Code Quality

# Format code
uv run black src/ tests/
uv run isort src/ tests/

# Lint code
uv run ruff check src/ tests/
uv run mypy src/

# All checks
uv run ruff check src/ tests/ && uv run mypy src/ && uv run pytest

Project Structure

ceph-mcp-server/
├── src/ceph_mcp/
│   ├── __init__.py          # Package initialization
│   ├── server.py            # Main MCP server
│   ├── api/
│   │   └── ceph_client.py   # Ceph API client
│   ├── config/
│   │   └── settings.py      # Configuration management
│   ├── handlers/
│   │   └── health_handlers.py # Request handlers
│   ├── models/
│   │   └── ceph_models.py   # Data models
│   └── utils/               # Utility functions
├── tests/                   # Test suite
├── .env.example            # Environment template
├── pyproject.toml          # Project configuration
└── README.md              # This file

🐛 Troubleshooting

Common Issues

1. Connection Refused

   • Check if Ceph Manager is running and accessible
   • Verify the URL and port in your configuration
   • Ensure network connectivity between MCP server and Ceph cluster

2. Authentication Failed

   • Verify username and password are correct
   • Check that the user has appropriate permissions
   • Ensure the Ceph user account is active

3. SSL Certificate Errors

   • For development: Set CEPH_SSL_VERIFY=false
   • For production: Use proper SSL certificates or specify CEPH_CERT_PATH

4. Permission Denied

   • Ensure the Ceph user has read permissions for health and host information
   • Check Ceph user capabilities: ceph auth get client.your-username

Debugging

Enable debug logging to get more detailed information:

LOG_LEVEL=DEBUG uv run python -m ceph_mcp.server

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes and add tests
4. Run the test suite: uv run pytest
5. Format code: uv run black src/ tests/
6. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Ceph Storage - The distributed storage system
• Model Context Protocol - The protocol enabling AI integration
• Anthropic - For developing MCP and Claude

📞 Support

• Create an issue for bug reports or feature requests
• Check existing issues before creating new ones
• Provide detailed information about your environment when reporting issues