Ceph MCP Server

# 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:** ```bash # 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:** ```bash # Copy the example environment file cp .env.example .env # Edit .env with your Ceph cluster details nano .env ``` 3. **Configure your Ceph connection:** ```bash # .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:** ```bash 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 ```bash # 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 ```bash # 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: ```bash 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](https://ceph.io/) - The distributed storage system - [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol enabling AI integration - [Anthropic](https://anthropic.com/) - 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