aphraz/cw-mcp

🚀 Cloudways MCP Server

An MCP (Model Context Protocol) server for seamless integration with the Cloudways API. This server enables AI assistants like Claude to access and manage your Cloudways infrastructure.

✨ Key Features

🔒 Security & Isolation

• Customer Isolation: Each customer gets encrypted, isolated data storage
• Encrypted API Keys: All sensitive data encrypted at rest using Fernet encryption
• Token Auto-Renewal: Proactive token refresh prevents authentication failures
• Rate Limiting: Token bucket algorithm with per-customer limits (90 req/min)

⚡ Performance & Reliability

• Connection Pooling: Optimized HTTP and Redis connection pools for high concurrency
• Background Token Refresh: Zero-downtime token renewal with race condition protection
• Distributed Locking: Redis-based locks prevent concurrent token refresh conflicts
• Graceful Fallbacks: Robust error handling with fallback mechanisms

📊 Monitoring & Observability

• Structured Logging: Comprehensive logging with structured data for debugging
• Token Status Monitoring: Real-time token health and expiration tracking
• Rate Limit Monitoring: Per-customer rate limit status and usage analytics
• Customer Analytics: Track customer usage patterns and last activity

🛠️ Current Capabilities (Read-Only)

• ✅ Server Management: List, monitor, and inspect server configurations
• ✅ Application Management: Access app details, credentials, and settings
• ✅ Monitoring Data: Bandwidth, disk usage, and performance metrics
• ✅ Team & Projects: View team members, projects, and organizational structure
• ✅ Infrastructure Discovery: Available providers, regions, sizes, and packages
• ✅ Alerting: Access all system alerts and notifications

🚧 Future Roadmap

• 🔄 Write Operations: Create, modify, and delete resources
• 🎛️ Server Management: Start, stop, restart, and scale servers
• 📦 Application Deployment: Deploy new applications and manage existing ones
• ⚙️ Configuration Management: Update server and application settings
• 🔐 Security Operations: Manage SSH keys, SSL certificates, and firewall rules

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Claude AI     │────│  MCP Server     │────│  Cloudways API  │
│                 │    │                 │    │                 │
│ • Natural Lang  │    │ • Token Mgmt    │    │ • REST Endpoints│
│ • Context Aware │    │ • Rate Limiting │    │ • Authentication│
│ • Multi-tenant  │    │ • Encryption    │    │ • Resource Data │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              │
                       ┌─────────────────┐
                       │   Redis Cache   │
                       │                 │
                       │ • Token Storage │
                       │ • Rate Limits   │
                       │ • Customer Data │
                       └─────────────────┘

🚀 Quick Start

Prerequisites

• Python 3.8+ - For running the MCP server
• Node.js 18+ and NPM - Required for Claude Desktop to connect via npx mcp-remote
• Redis server - For production features (token management, rate limiting, customer isolation)
• Cloudways account with API access
• Homebrew (macOS) - For easy installation of dependencies

Installation

1. Install System Dependencies (macOS)

Install Node.js and NPM:

# Using Homebrew (recommended)
brew install node

# Verify installation
node --version  # Should show v18+ 
npm --version   # Should show npm version

Install and Setup Redis:

# Install Redis using Homebrew
brew install redis

# Start Redis as a background service (auto-restart on boot)
brew services start redis

# Verify Redis is running
redis-cli ping  # Should respond with "PONG"

Alternative Redis Setup:

# If you prefer to run Redis manually (not as a service)
/opt/homebrew/opt/redis/bin/redis-server /opt/homebrew/etc/redis.conf

# To stop the Redis service later
brew services stop redis

2. Clone and Setup Project

Clone the repository:

git clone <repository-url>
cd cloudways-mcp

Create Python virtual environment:

python3 -m venv venv
source venv/bin/activate  # On macOS/Linux

Install Python dependencies:

pip install -r requirements.txt

3. Configure Environment Variables

Create a .env file in the project root:

# Environment Variables for Cloudways MCP Server

# Encryption key (auto-generated if not set)
ENCRYPTION_KEY=""

# Redis connection URL
REDIS_URL="redis://localhost:6379/0"

# Rate limiting configuration (requests per minute per customer)
RATE_LIMIT_REQUESTS="90"

# Optional: Logging level
LOG_LEVEL="INFO"

4. Start the MCP Server

# Make sure you're in the virtual environment
source venv/bin/activate

# Start the server
python cw-mcp.py

The server will start on http://127.0.0.1:7000/mcp and you should see:

==================================================
🚀 Cloudways MCP Server
==================================================
INFO: Started server process [XXXX]
INFO: Uvicorn running on http://127.0.0.1:7000 (Press CTRL+C to quit)

5. Verify Setup

Test Redis Connection:

redis-cli ping  # Should return "PONG"

Test MCP Server:

# Check if server is running
curl -v "http://127.0.0.1:7000/mcp/"
# Should return a 406 error (expected - means server is working)

Check Server Logs: The server logs will show successful startup and any connection attempts from Claude Desktop.

🔧 Claude Desktop Integration

Configuration File Location

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

Example Configuration

{
  "mcpServers": {
    "cloudways": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:7000/mcp",
        "--header",
        "x-cloudways-email: ${CLOUDWAYS_EMAIL}",
        "--header",
        "x-cloudways-api-key: ${CLOUDWAYS_API_KEY}"
      ],
      "env": {
        "CLOUDWAYS_EMAIL": "your@cloudways-email.com",
        "CLOUDWAYS_API_KEY": "your-cloudways-api-key"
      }
    }
  }
}

Getting Your API Key

1. Log into Cloudways Platform
2. Go to Account Settings → API
3. Generate or copy your API key

🛠️ Available Tools

🖥️ Server Operations

📱 Application Operations

📊 Monitoring & Analytics

👥 Organization & Projects

🌐 Infrastructure Discovery

🔧 System & Debugging

💬 Example Claude Conversations

Server Management

You: "Show me all my Cloudways servers and their status"
Claude: I'll get your server list and check their status...

You: "Which server is using the most bandwidth this month?"
Claude: Looking at your server monitoring data...

You: "Show me the PHP version on server 12345"
Claude: Let me check the server details and package information...

Application Management

You: "What are the database credentials for my e-commerce app?"
Claude: I'll retrieve the application credentials securely...

You: "Show me all WordPress sites across all my servers"
Claude: Let me scan through your applications to find WordPress installations...

Infrastructure Planning

You: "I want to deploy a new Laravel app. What options do I have?"
Claude: Let me show you available server sizes, and regions...

🔒 Security & Privacy

Data Protection

• Encryption at Rest: All API keys encrypted using Fernet symmetric encryption
• Customer Isolation: Each customer's data is completely isolated and namespaced
• No Data Persistence: Tokens and sensitive data have automatic expiration
• Memory-Safe: Sensitive data cleared from memory after use

Authentication Flow

1. Header-Based Auth: Credentials passed via headers
2. Token Exchange: API key exchanged for short-lived access tokens
3. Proactive Renewal: Tokens refreshed 5 minutes before expiry
4. Race Protection: Distributed locks prevent concurrent refresh attempts

Rate Limiting

• Per-Customer Limits: 90 requests per minute per customer
• Token Bucket Algorithm: Smooth traffic distribution
• Graceful Degradation: Clear error messages when limits exceeded

Debug Mode

Enable verbose logging:

export LOG_LEVEL=DEBUG
python cw-mcp.py

🔧 Troubleshooting

Common Issues and Solutions

Node.js/NPM Issues

Problem: zsh: command not found: node

# Solution: Install Node.js
brew install node

# If Homebrew is not installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Problem: npx: command not found

# NPX comes with npm, reinstall Node.js
brew uninstall node
brew install node

Redis Issues

Problem: Connection refused when testing Redis

# Check if Redis is running
brew services list | grep redis

# Start Redis if not running
brew services start redis

# If Redis was installed via different method
redis-server /opt/homebrew/etc/redis.conf

Problem: Redis connection timeout

# Check Redis status
redis-cli ping

# If Redis is on different port/host, update .env file
REDIS_URL="redis://localhost:6380/0"  # Use correct port

MCP Server Issues

Problem: ModuleNotFoundError when starting server

# Ensure virtual environment is activated
source venv/bin/activate

# Reinstall dependencies
pip install -r requirements.txt

Problem: Port 7000 already in use

# Find process using port 7000
lsof -i :7000

# Kill the process (replace PID with actual process ID)
kill -9 <PID>

# Or use a different port by modifying cw-mcp.py

Problem: Server starts but Claude Desktop can't connect

# Verify server is listening
curl -v "http://127.0.0.1:7000/mcp/"

# Should return 406 error (this is correct!)
# Check Claude Desktop config file has correct URL

Claude Desktop Connection Issues

Problem: MCP server not recognized by Claude Desktop

1. Restart Claude Desktop completely
2. Check the configuration file location:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
3. Verify JSON syntax is valid
4. Ensure the MCP server is running before starting Claude Desktop

Problem: Authentication errors

1. Verify your Cloudways credentials are correct
2. Check that your API key has proper permissions
3. Test credentials manually via Cloudways API

Cloudways API Issues

Problem: Invalid API key errors

# Test your credentials directly
curl -X POST "https://api.cloudways.com/api/v1/oauth/access_token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "email=your@email.com&api_key=your-api-key"

Problem: Rate limiting errors

• The server implements 90 requests/minute per customer
• Wait a minute and try again
• Check server logs for rate limit status

Getting Help

Enable Debug Logging:

# In your .env file
LOG_LEVEL=DEBUG

# Or export temporarily
export LOG_LEVEL=DEBUG
python cw-mcp.py

Check Server Status:

# Process check
ps aux | grep cw-mcp

# Port check  
lsof -i :7000

# Connection test
curl -v "http://127.0.0.1:7000/mcp/"

🆘 Support

• Issues: Open a GitHub issue for bugs or feature requests

⚠️ Current Limitation: This server currently supports read-only operations only. Write operations (create, update, delete) are planned for future releases to ensure maximum safety and reliability.