hyperbolic-mcp

Hyperbolic GPU MCP Server

Interact with Hyperbolic's GPU cloud, enabling agents and LLMs to view and rent available GPUs, SSH into them, and run GPU-powered workloads for you.

https://github.com/user-attachments/assets/814d0327-ce5e-4c1b-90bc-7f3712aa1c68

Setup

Prerequisites

• Node.js 16 or higher
• npm or yarn
• A Hyperbolic API token
• (Optional) SSH private key for connecting to GPU instances

Getting a Hyperbolic Account and API Token

1. Register for a Hyperbolic account:

   • Visit https://app.hyperbolic.xyz/
   • Create an account or log in to your existing account
   • Verify your email address

2. Deposit funds into your account:

   • Log in to your Hyperbolic application
   • Navigate to the "Billing" tab
   • Select how much you want to deposit (we suggest starting with $25)
   • Click Pay Now
   • Follow the instructions to add funds to your account
   • Note that you will need sufficient funds to rent GPU instances

3. Generate an API token:

   • In your Hyperbolic dashboard, navigate to "Settings"
   • Navigate to the API Key section
   • Copy the generated token and keep it secure
   • You will use this key in your MCP server configuration environment variables

4. Add your SSH public key:

   • Generate an SSH key pair if you don't already have one
   • In your Hyperbolic application, navigate to the "Settings" section
   • Scroll down to the SSH Public Key section
   • Paste your public key (usually from ~/.ssh/id_rsa.pub or similar)
   • Click the save icon

Installation

1. Clone this repository:

   git clone <your-repo-url>
   cd hyperbolic-mcp
   

2. Install dependencies:

   npm install
   

3. Build the TypeScript files:

   npm run build
   

Usage

Running the server locally

To run the server:

npm start

Connecting with Claude for Desktop

1. Add the server to your Claude for Desktop config:

{
  "mcpServers": {
    "hyperbolic-gpu": {
      "command": "node",
      "args": ["/path/to/hyperbolic-mcp-server/build/index.js"],
      "env": {
        "HYPERBOLIC_API_TOKEN": "your-hyperbolic-api-token",
        "SSH_PRIVATE_KEY_PATH": "/path/to/your/privatekey" 
      }
    }
  }
}

2. Restart Claude for Desktop.

3. Start a new conversation and interact with the server.

Note: You can provide environment variables either through the Claude Desktop config as shown above, or by creating a .env file in the project root. The .env file is only needed if you're not providing the variables through the config.

Available Tools

The server provides the following tools:

GPU Management Tools

list-available-gpus

Lists all available GPUs on the Hyperbolic network.

Example query: "Show me all available GPUs on Hyperbolic."

rent-gpu-instance

Rents a GPU instance from a specific cluster.

Parameters:

• cluster_name: The name of the cluster to rent (e.g., "extrasmall-chamomile-duck")
• node_name: The name of the node (e.g., "prd-acl-msi-02.fen.intra")
• gpu_count: Number of GPUs to rent

Example query: "I want to rent 4 GPUs from the extrasmall-chamomile-duck cluster."

terminate-gpu-instance

Terminates a GPU instance that you have rented.

Parameters:

• instance_id: The ID of the instance to terminate

Example query: "Terminate my GPU instance with ID abc123."

list-user-instances

Lists all active GPU instances that you have rented.

Example query: "Show me all my active GPU instances."

get-cluster-details

Gets detailed information about a specific cluster.

Parameters:

• cluster_name: The name of the cluster to get details for

Example query: "Tell me more about the cluster called extrasmall-chamomile-duck."

SSH Tools

ssh-connect

Establishes an SSH connection to a remote server.

Parameters:

• host: Hostname or IP address of the remote server
• username: SSH username for authentication
• password: (Optional) SSH password for authentication
• private_key_path: (Optional) Path to private key file
• port: (Optional) SSH port number (default: 22)

Example query: "Connect to my GPU instance at 192.168.1.100 as user admin."

remote-shell

Executes a command on the connected remote server.

Parameters:

• command: Command to execute on the remote server

Example query: "Run 'nvidia-smi' on the connected server."

ssh-status

Checks the current SSH connection status.

Example query: "What's the status of my SSH connection?"

ssh-disconnect

Closes the active SSH connection.

Example query: "Disconnect from the SSH server."

Security Notes

• This server requires your Hyperbolic API token and optionally an SSH private key
• These credentials can be provided either through the Claude Desktop config or a .env file
• The server only runs locally and doesn't expose your credentials externally
• Commands to rent GPUs will incur charges on your Hyperbolic account
• The SSH private key must not be password protected as the server cannot handle password-protected keys

Troubleshooting

If you encounter issues:

1. Check that your API token is correct and not expired
2. Ensure you have sufficient credits on your Hyperbolic account
3. Check the server logs for error messages
4. Verify your network connection to the Hyperbolic API
5. If using SSH, verify that your private key path is correct and the key has the right permissions.

License

MIT License