Hyperbolic GPU MCP Server

What is Hyperbolic GPU MCP Server about?

Enables seamless interaction with Hyperbolic's GPU cloud from within Claude or other AI agents. It exposes tools for discovering available GPUs, renting instances, terminating them, and establishing SSH connections for remote command execution.

How to use Hyperbolic GPU MCP Server?

1. Prerequisites: Install Node.js 16+, npm/yarn, obtain a Hyperbolic API token, and optionally generate an SSH key pair.
2. Installation:

   git clone <repo-url>
   cd hyperbolic-mcp
   npm install
   npm run build
   

3. Run locally:

   npm start
   

4. Connect via Claude for Desktop – add a server entry to Claude's config JSON, supplying HYPERBOLIC_API_TOKEN and SSH_PRIVATE_KEY_PATH either in the env block or a .env file.
5. Issue tool commands (e.g., list-available-gpus, rent-gpu-instance) within a conversation to manage GPU resources.

Key features of Hyperbolic GPU MCP Server

• GPU Management Tools: list available GPUs, rent instances with specified cluster, node, and GPU count, terminate instances, list user‑owned instances, fetch cluster details.
• SSH Tools: establish SSH connections, run remote commands, check connection status, and disconnect.
• Security‑focused: credentials stay local; API token and private key are supplied via environment variables.
• Integration ready: designed for Claude for Desktop but usable by any MCP‑compatible client.

Use cases of Hyperbolic GPU MCP Server

• AI model fine‑tuning: dynamically rent GPU nodes, SSH in, run training scripts, then terminate to control costs.
• On‑demand inference: spin up a GPU instance for heavy inference tasks and shut down after completion.
• Research experimentation: explore different GPU clusters, gather performance metrics via nvidia-smi.
• Automated pipelines: embed tool calls in agent workflows to provision resources without manual intervention.

FAQ from the Hyperbolic GPU MCP Server

• Where do I get a Hyperbolic API token? Register at https://app.hyperbolic.xyz/, navigate to Settings → API Key, and copy the generated token.
• Do I need to fund my account? Yes, renting GPUs incurs charges. Deposit funds via the Billing tab in the Hyperbolic dashboard.
• Can I use a password‑protected SSH key? No, the server cannot handle password‑protected keys; use an unencrypted private key.
• What Node version is required? Node.js 16 or higher.
• How are credentials protected? They are only read from environment variables or a local .env file and never transmitted externally.
• What happens if I exceed my credit? API calls to rent GPUs will fail; ensure sufficient balance before provisioning.
• Can I run the server on a remote machine? Yes, as long as the environment variables are set and the machine can reach the Hyperbolic API.

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