ray-mcp-server

⚡ Ray MCP Server

🚀 Supercharge your AI workflows with distributed computing!

A powerful Model Context Protocol (MCP) server that brings Ray's distributed computing capabilities directly to Claude Desktop. Manage clusters, submit jobs, and orchestrate complex workflows through natural language commands! 🎯

✨ Features

• 🏗️ Multi-Node Cluster Management: Start and manage Ray clusters with head nodes and worker nodes
• 🚀 Job Management: Submit, monitor, and manage Ray jobs with ease
• 🎭 Actor Management: Create and manage Ray actors for stateful computations
• 📊 Real-time Monitoring: Get cluster status, resource usage, and performance metrics
• 🔍 Logging and Debugging: Access logs and debug job issues seamlessly
• ⏰ Scheduling: Schedule jobs with cron-like syntax for automated workflows

🚀 Quick Start

📦 Installation

🚀 Super Easy with uvx (Recommended):

# Install and run directly with uvx - no setup needed! ⚡
uvx ray-mcp-server

📥 Or clone for development:

# Clone the repository
git clone <repository-url>
cd ray-mcp

# Install dependencies with UV (lightning fast! ⚡)
uv sync

# You're ready to go! 🎉

🎯 Starting Ray Clusters

The server supports both single-node and multi-node cluster configurations:

🖥️ Simple Single-Node Cluster

{
  "tool": "start_ray",
  "arguments": {
    "num_cpus": 4,
    "num_gpus": 1
  }
}

🌐 Multi-Node Cluster (Default)

The server now defaults to starting multi-node clusters with 2 worker nodes (perfect for scaling! 📈):

{
  "tool": "start_ray",
  "arguments": {
    "num_cpus": 1
  }
}

This creates:

• 🧠 Head node: 1 CPU, 0 GPUs, 1GB object store memory
• ⚙️ Worker node 1: 2 CPUs, 0 GPUs, 500MB object store memory
• ⚙️ Worker node 2: 2 CPUs, 0 GPUs, 500MB object store memory

🛠️ Custom Multi-Node Setup

For advanced configurations, you can specify custom worker nodes:

{
  "tool": "start_ray",
  "arguments": {
    "num_cpus": 4,
    "num_gpus": 0,
    "object_store_memory": 1000000000,
    "worker_nodes": [
      {
        "num_cpus": 2,
        "num_gpus": 0,
        "object_store_memory": 500000000,
        "node_name": "cpu-worker-1"
      },
      {
        "num_cpus": 4,
        "num_gpus": 1,
        "object_store_memory": 1000000000,
        "node_name": "gpu-worker-1",
        "resources": {"custom_resource": 2}
      }
    ],
    "head_node_port": 10001,
    "dashboard_port": 8265,
    "head_node_host": "127.0.0.1"
  }
}

💫 Basic Usage

Just ask Claude Desktop naturally! 🗣️

• "What's my Ray cluster status?"
• "Submit a job to process my data"
• "Show me cluster resources"
• "List all running jobs"

Or use direct tool calls:

{
  "tool": "cluster_status"
}

🛠️ Available Tools

20+ powerful tools for comprehensive Ray management! 💪

🏗️ Cluster Operations

• 🚀 start_ray - Start a new Ray cluster with head node and optional worker nodes
• 🔗 connect_ray - Connect to an existing Ray cluster
• 🛑 stop_ray - Stop the current Ray cluster
• 📊 cluster_status - Get comprehensive cluster status
• 💾 cluster_resources - Get resource usage information
• 🖥️ cluster_nodes - List all cluster nodes
• ⚙️ worker_status - Get detailed status of worker nodes

🚀 Job Operations

• 📤 submit_job - Submit a new job to the cluster
• 📋 list_jobs - List all jobs (running, completed, failed)
• 🔍 job_status - Get detailed status of a specific job
• ❌ cancel_job - Cancel a running or queued job
• 👀 monitor_job - Monitor job progress in real-time
• 🐛 debug_job - Debug a job with detailed information
• 📜 get_logs - Retrieve job logs and outputs

🎭 Actor Operations

• 👥 list_actors - List all actors in the cluster
• 💀 kill_actor - Terminate a specific actor

📈 Enhanced Monitoring

• ⚡ performance_metrics - Get detailed cluster performance metrics
• 🏥 health_check - Perform comprehensive cluster health check
• 🎯 optimize_config - Get cluster optimization recommendations

⏰ Job Scheduling

• 📅 schedule_job - Configure job scheduling parameters

📚 Examples

Ready-to-run examples in the examples/ directory:

• 🎯 simple_job.py - Basic Ray job example (start here!)
• 🌐 multi_node_cluster.py - Multi-node cluster with worker management
• 🎭 actor_example.py - Actor-based stateful computation
• 🔄 data_pipeline.py - Scalable data processing pipeline
• 🤖 distributed_training.py - Distributed machine learning
• 🎼 workflow_orchestration.py - Complex workflow orchestration

🔌 Claude Desktop Integration

⚡ Quick Setup

• 🎯 Choose your installation method:

  Option A: uvx (Easiest! 🚀)

  # No installation needed! uvx handles everything
  

  Option B: Development setup

  git clone <repository-url>
  cd ray-mcp
  uv sync
  

• ⚙️ Add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

  For uvx installation:

  {
    "mcpServers": {
      "ray-mcp": {
        "command": "uvx",
        "args": ["ray-mcp-server"]
      }
    }
  }
  

  For development setup:

  {
    "mcpServers": {
      "ray-mcp": {
        "command": "/opt/homebrew/bin/uv",
        "args": ["run", "--directory", "/absolute/path/to/ray-mcp", "ray-mcp-server"]
      }
    }
  }
  

• 🌐 For remote Ray clusters (like Kubernetes), add port-forwarding and environment:

  kubectl port-forward -n ray-cluster ray-cluster-kuberay-head-<pod-id> 10001:10001
  

  For uvx:

  {
    "mcpServers": {
      "ray-mcp": {
        "command": "uvx",
        "args": ["ray-mcp-server"],
        "env": {
          "RAY_ADDRESS": "ray://127.0.0.1:10001"
        }
      }
    }
  }
  

• 🔄 Restart Claude Desktop and test with: "What Ray tools are available?" 🎉

📖 Detailed Setup Guides

• 🚢 Kubernetes Ray Clusters: See docs/KUBERNETES_SETUP.md
• ⚙️ Configuration Examples: See docs/config/
• 👨‍💻 Development Guide: See CLAUDE.md

🛠️ Development

🧪 Running Tests

# Run all tests
uv run pytest

# Run specific test categories
uv run pytest tests/test_mcp_tools.py
uv run pytest tests/test_multi_node_cluster.py
uv run pytest tests/test_e2e_integration.py

✨ Code Quality

# Run linting and formatting checks
make lint

# Format code automatically
make format

# Run type checking
uv run pyright ray_mcp/

# Run code formatting
uv run black ray_mcp/
uv run isort ray_mcp/

📄 License

This project is licensed under the Apache License, Version 2.0 - see the LICENSE file for details.

This software includes code originally from ray-mcp licensed under the MIT License. See NOTICE file for full attribution details.

Ready to supercharge your Ray workflows? Get started now! 🚀✨