Vast.ai

- Install uv(Python package manager):

brew install uv

git clone https://github.com/your-repo/vastai-mcp.git cd vastai-mcp

uv tool install -e . # Install from current directory

- Log in toconsole.vast.ai
- Go to Account > API Keys
- Create or copy your API key

{ "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" } } } }

- Test the server directly:

uv tool run vast-mcp-server --help

For full functionality, ensure you have SSH keys set up:
-

Generate SSH key pair(if you don't have one):

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

You should see bothid_rsa(private) andid_rsa.pub(public) files.

-

Permission denied: Make sure your SSH key has correct permissions:

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 reachconsole.vast.aifrom your network

This document describes how to use the Vast.ai MCP (Model Context Protocol) server to interact with the Vast.ai GPU cloud platform.

This server provides23 toolsfor managing Vast.ai GPU instances:

Show current user information and account balance.

- 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.)

- owner(optional): Owner of instances to show (default: "me")

- 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.

- 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-")

- 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

- "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)

- 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

- Success message with instance ID or error details

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" )

Destroy an instance, completely removing it from the system. Don't need to stop it first.

- instance_id: ID of the instance to destroy

- instance_id: ID of the instance to start

Stop a running instance (without destroying it).

- instance_id: ID of the instance to stop

8. search_volumes(query: str = "", limit: int = 20)

Search for available storage volume offers.

- query(optional): Search query in key=value format
- limit(optional): Maximum number of results to return (default: 20)

- 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.

- instance_id: ID of the instance to label
- label: Label text to set

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).

- 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

- Success message with instance details or error

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.

- instance_id: ID of the instance to prepay
- amount: Amount of credits to deposit

- Details about discount rate and coverage period

Reboot an instance (stop/start) without losing GPU priority.

- instance_id: ID of the instance to reboot

Recycle an instance (destroy/create from newly pulled image) without losing GPU priority.

- instance_id: ID of the instance to recycle

Show detailed information about a specific instance.

- instance_id: ID of the instance to show

- 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)

- 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

Attach an SSH key to an instance for secure access.

- instance_id: ID of the instance to attach SSH key to

# Attach SSH key from configured public key file attach_ssh(12345)

- 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

Search for available templates on Vast.ai.

- List of available templates with:

- Template ID and name
- Docker image
- Description (if available)
- Environment variables
- Run type configuration
- SSH and Jupyter settings

# Get all available templates search_templates()

- 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.

- instance_id: ID of the instance to execute command on
- command: Command to execute (limited to ls, rm, du)

- ls: List directory contents
- rm: Remove files or directories
- du: Summarize device usage for a set of files

# 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")

- 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.