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:

2. Set up your environment:

3. Configure your Ceph connection:

🏃‍♂️ Quick Start

1. Start the 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

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

Troubleshooting

🧪 Development

Running Tests

Code Quality

Project Structure

🐛 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:

🤝 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