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:

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

Configuration

VS Code Configuration

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

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

3. Find the absolute path to the mcp-server directory:

# For example:
pwd

4. 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": []
    }
  }
}

5. 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": []
    }
  }
}

6. Save the file and restart VS Code

Claude Desktop Configuration

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

2. Edit the configuration file:

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

3. 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": []
    }
  }
}

4. Save the file and restart Claude Desktop

Cursor Configuration

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

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