Vast.ai MCP Server

# Installation ## macOS Installation Guide ### Prerequisites 1. **Install uv** (Python package manager): ```bash brew install uv ``` ### Install the Vast.ai MCP Server 1. **Clone the repository**: ```bash git clone https://github.com/your-repo/vastai-mcp.git cd vastai-mcp ``` 2. **Install dependencies using uv**: ```bash uv sync ``` 3. **Install the server as a tool**: ```bash uv tool install -e . # Install from current directory ``` ### Configuration 1. **Get your Vast.ai API key**: - Log in to [console.vast.ai](https://console.vast.ai) - Go to Account > API Keys - Create or copy your API key 3. **Configure MCP client** (for Claude Desktop or other MCP clients): Update your MCP configuration file (`~/.cursor/mcp.json` for Cursor): ```json { "mcpServers": { "vast-ai": { "command": "uv", "args": [ "run", "vast-mcp-server" ], "env": { "VAST_API_KEY": "your_vast_api_key_here", "SSH_KEY_FILE": "~/.ssh/id_rsa", "SSH_KEY_PUBLIC_FILE": "~/.ssh/id_rsa.pub" } } } } ``` ### Verify Installation 1. **Test the server directly**: ```bash uv tool run vast-mcp-server --help ``` ### SSH Key Setup (Recommended) For full functionality, ensure you have SSH keys set up: 1. **Generate SSH key pair** (if you don't have one): ```bash ssh-keygen -t rsa -b 4096 -C "your_email@example.com" ``` 2. **Verify key files exist**: ```bash ls -la ~/.ssh/id_rsa* ``` You should see both `id_rsa` (private) and `id_rsa.pub` (public) files. ### Troubleshooting - **Permission denied**: Make sure your SSH key has correct permissions: ```bash chmod 600 ~/.ssh/id_rsa chmod 644 ~/.ssh/id_rsa.pub ``` - **API key issues**: Verify your API key is correct and has proper permissions on Vast.ai - **Network issues**: Ensure you can reach `console.vast.ai` from your network # Vast.ai MCP Server Usage Guide This document describes how to use the Vast.ai MCP (Model Context Protocol) server to interact with the Vast.ai GPU cloud platform. ## Available Tools This server provides **23 tools** for managing Vast.ai GPU instances: ### 1. show_user_info() Show current user information and account balance. **Returns:** - Username, email, account balance, user ID - SSH key information (if available) - Total spent amount ### 2. show_instances(owner: str = "me") Show user's instances (running, stopped, etc.) **Parameters:** - `owner` (optional): Owner of instances to show (default: "me") **Returns:** - List of all instances with their details: - Instance ID and status - Label and machine ID - GPU type and specifications - Hourly cost - Docker image - Public IP address (if available) - Creation date ### 3. search_offers(query: str = "", limit: int = 20, order: str = "score-") Search for available GPU offers/machines to rent. **Parameters:** - `query` (optional): Search query in key=value format (e.g., "gpu_name=RTX_4090 num_gpus=2") - `limit` (optional): Maximum number of results to return (default: 20) - `order` (optional): Sort order, append '-' for descending (default: "score-") **Returns:** - List of available offers with: - Offer ID - GPU specifications (name, count) - CPU and RAM details - Storage space - Hourly cost - Location and reliability score - CUDA version - Internet speeds **Example queries:** - `"gpu_name=RTX_4090"` - Search for RTX 4090 GPUs - `"num_gpus=2 cpu_ram>=32"` - Search for dual GPU setups with 32GB+ RAM ### 4. create_instance(offer_id: int, image: str, disk: float = 10.0, ssh: bool = False, jupyter: bool = False, direct: bool = False, env: str = "", label: str = "", bid_price: float = None) Create a new instance from an offer. **Parameters:** - `offer_id`: ID of the offer to rent (from search_offers) - `image`: Docker image to run (e.g., "pytorch/pytorch:latest") - `disk` (optional): Disk size in GB (default: 10.0) - `ssh` (optional): Enable SSH access (default: False) - `jupyter` (optional): Enable Jupyter notebook (default: False) - `direct` (optional): Use direct connections (default: False) - `env` (optional): Environment variables as dict (default: None) - `label` (optional): Label for the instance - `bid_price` (optional): Bid price for interruptible instances **Returns:** - Success message with instance ID or error details **Example:** ``` create_instance( offer_id=12345, image="pytorch/pytorch:latest", disk=40.0, ssh=True, direct=True, env={"JUPYTER_ENABLE_LAB": "yes"}, label="My PyTorch Training" ) ``` ### 5. destroy_instance(instance_id: int) Destroy an instance, completely removing it from the system. Don't need to stop it first. **Parameters:** - `instance_id`: ID of the instance to destroy **Returns:** - Success/failure message ### 6. start_instance(instance_id: int) Start a stopped instance. **Parameters:** - `instance_id`: ID of the instance to start **Returns:** - Success/failure message ### 7. stop_instance(instance_id: int) Stop a running instance (without destroying it). **Parameters:** - `instance_id`: ID of the instance to stop **Returns:** - Success/failure message ### 8. search_volumes(query: str = "", limit: int = 20) Search for available storage volume offers. **Parameters:** - `query` (optional): Search query in key=value format - `limit` (optional): Maximum number of results to return (default: 20) **Returns:** - List of available volume offers with: - Volume offer ID - Storage capacity - Cost per GB per month - Location and reliability - Disk bandwidth - Internet speeds ### 9. label_instance(instance_id: int, label: str) Set a label on an instance for easier identification. **Parameters:** - `instance_id`: ID of the instance to label - `label`: Label text to set **Returns:** - Success/failure message ### 10. launch_instance_workflow(gpu_name: str, num_gpus: int, image: str, region: str = "", disk: float = 16.0, ssh: bool = True, jupyter: bool = False, direct: bool = True, label: str = "") Launch the top instance from search offers based on given parameters (streamlined alternative to create_instance). **Parameters:** - `gpu_name`: Name of GPU model (e.g., "RTX_4090") - `num_gpus`: Number of GPUs required - `image`: Docker image to run - `region` (optional): Geographical region preference - `disk` (optional): Disk size in GB (default: 16.0) - `ssh` (optional): Enable SSH access (default: True) - `jupyter` (optional): Enable Jupyter notebook (default: False) - `direct` (optional): Use direct connections (default: True) - `label` (optional): Label for the instance **Returns:** - Success message with instance details or error **Example:** ``` launch_instance_workflow( gpu_name="RTX_4090", num_gpus=2, image="pytorch/pytorch:latest", region="North_America", disk=40.0, ssh=True, direct=True, label="My Training Job" ) ``` ### 11. prepay_instance(instance_id: int, amount: float) Deposit credits into a reserved instance for discounted rates. **Parameters:** - `instance_id`: ID of the instance to prepay - `amount`: Amount of credits to deposit **Returns:** - Details about discount rate and coverage period ### 12. reboot_instance(instance_id: int) Reboot an instance (stop/start) without losing GPU priority. **Parameters:** - `instance_id`: ID of the instance to reboot **Returns:** - Success/failure message ### 13. recycle_instance(instance_id: int) Recycle an instance (destroy/create from newly pulled image) without losing GPU priority. **Parameters:** - `instance_id`: ID of the instance to recycle **Returns:** - Success/failure message ### 14. show_instance(instance_id: int) Show detailed information about a specific instance. **Parameters:** - `instance_id`: ID of the instance to show **Returns:** - Detailed instance information including: - Status and specifications - Connection details (IP, SSH, Jupyter) - Cost and runtime information - Configuration details ### 15. logs(instance_id: int, tail: str = "1000", filter_text: str = "", daemon_logs: bool = False) Get logs for an instance. **Parameters:** - `instance_id`: ID of the instance to get logs for - `tail` (optional): Number of lines from end of logs (default: "1000") - `filter_text` (optional): Grep filter for log entries - `daemon_logs` (optional): Get daemon system logs instead of container logs **Returns:** - Instance logs text or status message ### 16. attach_ssh(instance_id: int) Attach an SSH key to an instance for secure access. **Parameters:** - `instance_id`: ID of the instance to attach SSH key to **Returns:** - Success/failure message **Examples:** ```python # Attach SSH key from configured public key file attach_ssh(12345) ``` **Notes:** - Uses the SSH public key file configured in SSH_KEY_PUBLIC_FILE environment variable - Only public SSH keys are accepted (not private keys) - SSH key must start with 'ssh-' prefix (e.g., ssh-rsa, ssh-ed25519) - After attaching, you can SSH to the instance using the corresponding private key ### 17. search_templates() Search for available templates on Vast.ai. **Parameters:** - None **Returns:** - List of available templates with: - Template ID and name - Docker image - Description (if available) - Environment variables - Run type configuration - SSH and Jupyter settings **Example:** ```python # Get all available templates search_templates() ``` **Notes:** - Templates are pre-configured environments that simplify instance creation - Templates may include specific Docker images, environment setups, and startup scripts ### 18. execute_command(instance_id: int, command: str) Execute a (constrained) remote command only available on stopped instances. Use ssh to run commands on running instances. **Parameters:** - `instance_id`: ID of the instance to execute command on - `command`: Command to execute (limited to ls, rm, du) **Returns:** - Command output or status message **Available commands:** - `ls`: List directory contents - `rm`: Remove files or directories - `du`: Summarize device usage for a set of files **Examples:** ```python # List directory contents execute_command(12345, "ls -l -o -r") # Remove files execute_command(12345, "rm -r home/delete_this.txt") # Check disk usage execute_command(12345, "du -d2 -h") ``` **Notes:** - Only works on stopped instances - For running instances, use ssh_execute_command instead - Limited to specific safe commands for security ### 19. ssh_execute_command(remote_host: str, remote_user: str, remote_port: int, command: str) Execute a command on a remote host via SSH. **Parameters:** - `remote_host`: The hostname or IP address of the remote server - `remote_user`: The username to connect as (e.g., 'root', 'ubuntu', 'ec2-user') - `remote_port`: The SSH port number (typically 22 or custom port like 34608) - `command`: The command to execute on the remote host **Returns:** - Command output with exit status, stdout, and stderr **Example:** ```python # Execute a command on a running instance ssh_execute_command( remote_host="116.43.148.85", remote_user="root", remote_port=26378, command="nvidia-smi" ) ``` **Notes:** - Works with any SSH-accessible server, not just Vast.ai instances - Uses the SSH private key file configured in SSH_KEY_FILE environment variable - Automatically handles different SSH key types (RSA, Ed25519, ECDSA, DSS) - Returns detailed output including exit status and both stdout/stderr ### 20. ssh_execute_background_command(remote_host: str, remote_user: str, remote_port: int, command: str, task_name: str = None) Execute a long-running command in the background on a remote host via SSH using nohup. **Parameters:** - `remote_host`: The hostname or IP address of the remote server - `remote_user`: The username to connect as (e.g., 'root', 'ubuntu', 'ec2-user') - `remote_port`: The SSH port number (typically 22 or custom port like 34608) - `command`: The command to execute in the background - `task_name` (optional): Optional name for the task (for easier identification) **Returns:** - Task information including task ID, process ID, and log file path **Example:** ```python # Start a long-running training job ssh_execute_background_command( remote_host="116.43.148.85", remote_user="root", remote_port=26378, command="python train.py --epochs 100", task_name="training_job" ) ``` **Notes:** - Returns task_id and process_id for monitoring - Creates log files on the remote server for output capture - Use ssh_check_background_task to monitor progress - Use ssh_kill_background_task to stop if needed ### 21. ssh_check_background_task(remote_host: str, remote_user: str, remote_port: int, task_id: str, process_id: int, tail_lines: int = 50) Check the status of a background SSH task and get its output. **Parameters:** - `remote_host`: The hostname or IP address of the remote server - `remote_user`: The username to connect as - `remote_port`: The SSH port number - `task_id`: The task ID returned by ssh_execute_background_command - `process_id`: The process ID returned by ssh_execute_background_command - `tail_lines` (optional): Number of recent log lines to show (default: 50) **Returns:** - Status report with process status, log output, and progress information **Example:** ```python # Check on a background task ssh_check_background_task( remote_host="116.43.148.85", remote_user="root", remote_port=26378, task_id="training_job_a1b2c3d4", process_id=12345, tail_lines=100 ) ``` **Notes:** - Shows whether the task is still running or completed - Displays recent log output from the task - Provides total log line count for progress indication ### 22. ssh_kill_background_task(remote_host: str, remote_user: str, remote_port: int, task_id: str, process_id: int) Kill a running background SSH task. **Parameters:** - `remote_host`: The hostname or IP address of the remote server - `remote_user`: The username to connect as - `remote_port`: The SSH port number - `task_id`: The task ID returned by ssh_execute_background_command - `process_id`: The process ID returned by ssh_execute_background_command **Returns:** - Status of the kill operation and cleanup results **Example:** ```python # Stop a background task ssh_kill_background_task( remote_host="116.43.148.85", remote_user="root", remote_port=26378, task_id="training_job_a1b2c3d4", process_id=12345 ) ``` **Notes:** - Attempts graceful termination first, then force kill if necessary - Automatically cleans up temporary log and PID files - Safe to call even if the process has already completed ### 23. disable_sudo_password(remote_host: str, remote_user: str, remote_port: int) Disable sudo password requirement for the sudo group on a remote host via SSH. This function safely modifies the sudoers file to allow passwordless sudo access for users in the sudo group. **Parameters:** - `remote_host`: The hostname or IP address of the remote server - `remote_user`: The username to connect as (e.g., 'root', 'ubuntu', 'ec2-user') - `remote_port`: The SSH port number (typically 22 or custom port like 34608) **Returns:** - Detailed status of the sudoers modification including: - Previous and new sudo configuration - Validation results - Backup file location **Example:** ```python # Disable sudo password on a running instance disable_sudo_password( remote_host="ssh1.vast.ai", remote_user="root", remote_port=26378 ) ``` **Safety Features:** - Creates automatic backup of sudoers file before modification - Validates sudoers syntax with `visudo -c` after changes - Automatically restores backup if validation fails - Shows before/after configuration for verification **Notes:** - Modifies sudoers to: `%sudo ALL=(ALL) NOPASSWD: ALL` - Requires the connecting user to have sudo privileges - Backup files are timestamped for safety - Works with any SSH-accessible Linux system - Test the change with `sudo -l` after execution ### 24. configure_mcp_rules(auto_attach_ssh: bool = None, auto_label: bool = None, wait_for_ready: bool = None, label_prefix: str = None) Configure MCP automation rules that control automatic behaviors during instance creation. **Parameters:** - `auto_attach_ssh` (optional): Enable/disable automatic SSH key attachment for SSH/Jupyter instances - `auto_label` (optional): Enable/disable automatic instance labeling - `wait_for_ready` (optional): Enable/disable waiting for instance readiness after creation - `label_prefix` (optional): Set the prefix for automatic instance labels **Returns:** - Current configuration status and any changes made **Example:** ```python # Configure MCP rules configure_mcp_rules( auto_attach_ssh=True, auto_label=True, label_prefix="my-project", wait_for_ready=True ) # View current configuration configure_mcp_rules() ``` **Notes:** - These rules affect the behavior of create_instance and launch_instance_workflow - Auto-attach SSH applies only when SSH or Jupyter is enabled - Auto-labeling creates timestamps labels when no label is provided - Wait for ready monitors instance status until it becomes "running" ## Configuration ### API Key Setup The server requires a Vast.ai API key. You can configure it in several ways: 1. **Environment Variable:** ```bash export VAST_API_KEY="your_api_key_here" ``` 2. **API Key File:** Create `~/.vastai_api_key` with your API key 3. **Hardcoded (for development):** The current server has a hardcoded API key for testing purposes ### Running the Server ```bash # Run with default settings (localhost:8000) python vast_mcp_server.py # Run with custom host and port python vast_mcp_server.py --host 0.0.0.0 --port 9000 ``` ## Common Workflows ### 1. Basic Instance Creation Workflow ```python # 1. Check your account show_user_info() # 2. Search for available offers search_offers("gpu_name=RTX_4090", limit=10) # 3. Create instance from an offer create_instance( offer_id=12345, image="pytorch/pytorch:latest", disk=20.0, ssh=True, direct=True ) # 4. Check instance status show_instances() ``` ### 2. Instance Management ```python # View all instances show_instances() # Stop an instance stop_instance(instance_id=67890) # Start it again later start_instance(instance_id=67890) # Permanently destroy when done destroy_instance(instance_id=67890) ``` ### 3. Finding Storage ```python # Search for storage volumes search_volumes("disk_space>=100", limit=5) ``` ### 4. Advanced Instance Management ```python # Launch instance with specific GPU requirements (streamlined approach) launch_instance_workflow( gpu_name="RTX_4090", num_gpus=2, image="pytorch/pytorch:latest", region="North_America", disk=40.0, ssh=True, direct=True, label="Training Job" ) # Get detailed information about an instance show_instance(instance_id=12345) # Set a label for easier identification label_instance(instance_id=12345, label="Production Model") # Get instance logs logs(instance_id=12345, tail="500", filter_text="error") # Reboot instance without losing GPU priority reboot_instance(instance_id=12345) ``` ### 5. Instance Monitoring and Maintenance ```python # Monitor instance logs with filtering logs(instance_id=12345, filter_text="WARNING|ERROR", tail="100") # Check instance details show_instance(instance_id=12345) # Recycle instance to update to latest image recycle_instance(instance_id=12345) # Prepay for discounted rates prepay_instance(instance_id=12345, amount=50.0) ``` ### 6. SSH Access Management ```python # Create instance with SSH enabled create_instance( offer_id=12345, image="ubuntu:22.04", ssh=True, direct=True, label="SSH Server" ) # Attach your SSH key for access attach_ssh(instance_id=67890) # Get instance details including SSH connection info show_instance(instance_id=67890) # Monitor instance through logs logs(instance_id=67890, tail="50") ``` ### 7. Template Browsing ```python # Browse available templates search_templates() ``` ### 8. Instance Command Execution ```python # For stopped instances, use constrained execute_command stop_instance(instance_id=12345) # Execute safe commands on stopped instance execute_command(instance_id=12345, command="ls -la /workspace") execute_command(instance_id=12345, command="du -sh /workspace") execute_command(instance_id=12345, command="rm -rf /tmp/old_files") # For running instances, use SSH commands start_instance(instance_id=12345) # Get instance connection details instance_details = show_instance(instance_id=12345) # Extract SSH host, port from the output # Execute commands via SSH on running instance ssh_execute_command( remote_host="116.43.148.85", remote_user="root", remote_port=26378, command="nvidia-smi" ) # Check system resources ssh_execute_command( remote_host="116.43.148.85", remote_user="root", remote_port=26378, command="df -h && free -h && ps aux" ) ``` ### 9. Background Task Management ```python # Start a long-running training job in background task_info = ssh_execute_background_command( remote_host="116.43.148.85", remote_user="root", remote_port=26378, command="python train.py --epochs 100 --batch-size 32", task_name="pytorch_training" ) # Extract task_id and process_id from task_info output # Format: "Task ID: pytorch_training_a1b2c3d4" and "Process ID: 12345" # Monitor progress periodically ssh_check_background_task( remote_host="116.43.148.85", remote_user="root", remote_port=26378, task_id="pytorch_training_a1b2c3d4", process_id=12345, tail_lines=100 ) # Stop the task if needed ssh_kill_background_task( remote_host="116.43.148.85", remote_user="root", remote_port=26378, task_id="pytorch_training_a1b2c3d4", process_id=12345 ) ``` ### 10. Complete ML Training Workflow ```python # 1. Find and create a GPU instance search_offers("gpu_name=RTX_4090", limit=5) create_instance( offer_id=12345, image="pytorch/pytorch:latest", disk=50.0, ssh=True, direct=True, env={}, label="ML Training" ) # 2. Get connection details instance_details = show_instance(instance_id=67890) # 3. Set up the environment ssh_execute_command( remote_host="116.43.148.85", remote_user="root", remote_port=26378, command="pip install wandb tensorboard" ) # 4. Upload your training code (assume already done) # 5. Start training in background training_task = ssh_execute_background_command( remote_host="116.43.148.85", remote_user="root", remote_port=26378, command="cd /workspace && python train.py --config config.yaml", task_name="main_training" ) # 6. Monitor training progress ssh_check_background_task( remote_host="116.43.148.85", remote_user="root", remote_port=26378, task_id="main_training_a1b2c3d4", process_id=12345, tail_lines=50 ) # 7. Check GPU utilization ssh_execute_command( remote_host="116.43.148.85", remote_user="root", remote_port=26378, command="nvidia-smi" ) # 8. When training is complete, save results ssh_execute_command( remote_host="116.43.148.85", remote_user="root", remote_port=26378, command="tar -czf model_results.tar.gz /workspace/outputs" ) # 9. Clean up destroy_instance(instance_id=67890) ``` ## Query Syntax When searching for offers or volumes, you can use these operators: - `=` or `==` - Equal to - `!=` - Not equal to - `>` - Greater than - `>=` - Greater than or equal to - `<` - Less than - `<=` - Less than or equal to **Example queries:** - `"gpu_name=RTX_4090 num_gpus>=2"` - RTX 4090 with 2 or more GPUs - `"cpu_ram>64 reliability2>=99"` - High RAM and reliability - `"dph_total<=1.0"` - Cost under $1/hour ## Error Handling All methods include error handling and will return descriptive error messages if: - API key is missing or invalid - Network connectivity issues occur - Invalid parameters are provided - Vast.ai API returns errors Check the server logs for detailed error information during development.