Spheron Network MCP Plugin

This MCP (Model Context Protocol) plugin integrates with the Spheron Protocol SDK to provide compute deployment and management capabilities directly through Claude.

Recent Fixes

ES Module Compatibility: Fixed fs-extra import to work properly with ES modules
BigInt Serialization: Added proper handling of BigInt values in API responses to prevent JSON serialization errors

Features

Deploy Compute Resources: Deploy compute resources using YAML configuration
Fetch Wallet Balance: Check your wallet balance for different tokens
Fetch Deployment URLs: Get URLs for your active deployments
Fetch Lease ID Details: Get detailed information about a lease

Installation

1. Clone the Repository

# Clone the repository
git clone https://github.com/spheronFdn/spheron-mcp-plugin.git

# Navigate to the project directory
cd spheron-mcp-plugin

2. Set Up Node.js Version

Using nvm (recommended)

# If you don't have nvm installed, install it first:
# For macOS/Linux:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# or
wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# For Windows (using Windows Subsystem for Linux or Git Bash):
# Follow instructions at https://github.com/nvm-sh/nvm

# Restart your terminal or run:
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# Use the project's Node.js version (defined in .nvmrc)
nvm use

# If you get an error that the version isn't installed:
nvm install
nvm use

Without nvm

If you're not using nvm, ensure your system Node.js version is 16.0.0 or higher:

# Check your Node.js version
node -v

# If it's below 16.0.0, download and install from nodejs.org
# https://nodejs.org/en/download/

3. Install Dependencies and Build

# Navigate to the server directory
cd spheron-server

# Install dependencies
npm install

# Build the project
npm run build

# Verify the build was successful
ls -la build

The build process will:

Compile TypeScript to JavaScript
Make the main file executable
Run the Node.js version check script

Configuration

VS Code Configuration

Locate or create the MCP settings file:

# For Linux:
mkdir -p ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/
touch ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

# For macOS:
mkdir -p ~/Library/Application\ Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/
touch ~/Library/Application\ Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

# For Windows:
# Create the file at %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

Edit the settings file with your configuration:

# Open the file in your preferred editor
# For example:
nano ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Find the absolute path to the mcp-server directory:

# For example:
pwd

Add the following configuration (adjust paths and keys as needed):

{
  "mcpServers": {
    "spheron": {
      "command": "node",
      "args": [
        "/absolute/path/to/spheron-mcp-plugin/mcp-server/build/index.js"
      ],
      "env": {
        "SPHERON_PRIVATE_KEY": "your-spheron-private-key",
        "SPHERON_NETWORK": "testnet",
        "PROVIDER_PROXY_URL": "https://provider-proxy.sphn.xyz",
        "YAML_API_URL": "http://149.56.15.95:8080/generate"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Or use the Docker configuration:

{
  "mcpServers": {
    "spheron": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "SPHERON_PRIVATE_KEY",
        "-e",
        "SPHERON_NETWORK",
        "-e",
        "PROVIDER_PROXY_URL",
        "-e",
        "YAML_API_URL",
        "saurrx/spheron-mcp:latest"
      ],
      "env": {
        "SPHERON_PRIVATE_KEY": "your-spheron-private-key",
        "SPHERON_NETWORK": "testnet",
        "PROVIDER_PROXY_URL": "https://provider-proxy.sphn.xyz",
        "YAML_API_URL": "http://149.56.15.95:8080/generate"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Save the file and restart VS Code

Claude Desktop Configuration

Locate or create the Claude Desktop configuration file:

# For macOS:
mkdir -p ~/Library/Application\ Support/Claude/
touch ~/Library/Application\ Support/Claude/claude_desktop_config.json

# For Windows:
# Create the file at %APPDATA%\Claude\claude_desktop_config.json

# For Linux:
mkdir -p ~/.config/Claude/
touch ~/.config/Claude/claude_desktop_config.json

Edit the configuration file:

# Open the file in your preferred editor
# For example:
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

Add the following configuration (adjust paths and keys as needed):

Docker Configuration

{
  "mcpServers": {
    "spheron": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "SPHERON_PRIVATE_KEY",
        "-e",
        "SPHERON_NETWORK",
        "-e",
        "PROVIDER_PROXY_URL",
        "-e",
        "YAML_API_URL",
        "saurrx/spheron-mcp:latest"
      ],
      "env": {
        "SPHERON_PRIVATE_KEY": "your-spheron-private-key",
        "SPHERON_NETWORK": "testnet",
        "PROVIDER_PROXY_URL": "https://provider-proxy.sphn.xyz",
        "YAML_API_URL": "http://149.56.15.95:8080/generate"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Node Configuration

Find the absolute path to the mcp-server directory:

# For example:
pwd

Add the following configuration:

{
  "mcpServers": {
    "spheron": {
      "command": "node",
      "args": [
        "/absolute/path/to/spheron-mcp-plugin/mcp-server/build/index.js"
      ],
      "env": {
        "SPHERON_PRIVATE_KEY": "your-spheron-private-key",
        "SPHERON_NETWORK": "testnet",
        "PROVIDER_PROXY_URL": "https://provider-proxy.sphn.xyz",
        "YAML_API_URL": "http://149.56.15.95:8080/generate"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Save the file and restart Claude Desktop

Cursor Configuration

Locate or create the Cursor configuration file:

# For macOS:
mkdir -p ~/Library/Application\ Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/
touch ~/Library/Application\ Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

# For Windows:
# Create the file at %APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

# For Linux:
mkdir -p ~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/
touch ~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Edit the configuration file:

# Open the file in your preferred editor
# For example:
nano ~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Usage

Once installed, you can use the Spheron Protocol MCP plugin through Claude with commands like:

Deploy Compute

Deploy this compute configuration:
version: "1.0"

services:
  py-cuda:
    image: quay.io/jupyter/pytorch-notebook:cuda12-pytorch-2.4.1
    expose:
      - port: 8888
        as: 8888
        to:
          - global: true
    env:
      - JUPYTER_TOKEN=sentient
profiles:
  name: py-cuda
  duration: 2h
  mode: provider
  tier:
    - community
  compute:
    py-cuda:
      resources:
        cpu:
          units: 8
        memory:
          size: 16Gi
        storage:
          - size: 200Gi
        gpu:
          units: 1
          attributes:
            vendor:
              nvidia:
                - model: rtx4090
  placement:
    westcoast:
      attributes:
        region: us-central
      pricing:
        py-cuda:
          token: CST
          amount: 10

deployment:
  py-cuda:
    westcoast:
      profile: py-cuda
      count: 1

Or say:

Deploy this jupyter notebook on Spheron

Check Wallet Balance

What's my CST balance on Spheron?

Get Deployment URLs

Show me the URLs for my deployment with lease ID 12345

Get Lease Details

Get details for lease ID 12345

Environment Variables

SPHERON_PRIVATE_KEY: Your Spheron private key for authentication
SPHERON_NETWORK: Network to use (testnet or mainnet)
PROVIDER_PROXY_URL: URL for the provider proxy server
YAML_API_URL: URL for the YAML generation API service

License

MIT