Sprite MCP Server

MCP server for managing Sprite VMs with interactive UI dashboards (MCP Apps).

Works with Claude.ai, Claude Desktop, Claude Code, VS Code, and any MCP-compatible client.

Features

List & manage Sprite VMs - Interactive dashboard with status indicators
Execute commands - Terminal UI with command history
Checkpoints - Create, list, restore filesystem snapshots
File transfer - Push/pull files to/from remote sprites
Session management - List, attach, kill sessions

Windows Setup (Claude Desktop / Claude Code)

Prerequisites

Node.js 20+ - Download from nodejs.org
Git - Download from git-scm.com
Sprite CLI - Get your token from sprites.dev

Step 1: Install Sprite CLI

Download and install the Sprite CLI for Windows:

# Using PowerShell (run as Administrator)
irm https://sprites.dev/install.ps1 | iex

Or download manually from sprites.dev/downloads.

Step 2: Authenticate with Sprite

Get your API token from the Sprites dashboard, then:

# Authenticate with your token
sprite auth setup --token "your-org/org-id/token-id/token-value"

# Or use interactive login (opens browser)
sprite login

Verify it works:

sprite list

Step 3: Clone and Build the MCP Server

# Clone the repository
git clone https://github.com/Anansitrading/sprite-mcp-server.git
cd sprite-mcp-server

# Install dependencies
npm install

# Build the server
npm run build

Step 4: Find Your Sprite CLI Path

# Find where sprite is installed
where sprite

This typically returns something like:

C:\Users\YourName\.local\bin\sprite.exe
C:\Users\YourName\AppData\Local\Programs\sprite\sprite.exe

Note this path - you'll need it for configuration.

Step 5: Configure Claude Desktop

Edit your Claude Desktop config file:

Location: %APPDATA%\Claude\claude_desktop_config.json

Open it with:

notepad "$env:APPDATA\Claude\claude_desktop_config.json"

Add this configuration (replace paths with your actual paths):

{
  "mcpServers": {
    "sprite": {
      "command": "node",
      "args": ["C:\\Users\\YourName\\sprite-mcp-server\\dist\\index.js"],
      "env": {
        "SPRITE_BIN": "C:\\Users\\YourName\\.local\\bin\\sprite.exe"
      }
    }
  }
}

Important: Use double backslashes (\\) in paths or forward slashes (/).

Step 6: Restart Claude Desktop

Fully quit Claude Desktop (check system tray)
Reopen Claude Desktop
Look for the hammer icon (🔨) indicating MCP tools are available

Step 7: Test It

Ask Claude:

"List my sprites"
"Execute ls -la on my sprite"
"Create a checkpoint"

Claude Code Setup (Windows)

For Claude Code CLI, add to your settings:

# Open Claude Code settings
claude mcp add sprite -- node "C:\Users\YourName\sprite-mcp-server\dist\index.js"

Or edit ~/.claude/settings.json:

{
  "mcpServers": {
    "sprite": {
      "command": "node",
      "args": ["C:\\Users\\YourName\\sprite-mcp-server\\dist\\index.js"],
      "env": {
        "SPRITE_BIN": "C:\\Users\\YourName\\.local\\bin\\sprite.exe"
      }
    }
  }
}

Linux/macOS Setup

Prerequisites

Node.js 20+
Sprite CLI configured with credentials

Quick Start

# Clone & build
git clone https://github.com/Anansitrading/sprite-mcp-server.git
cd sprite-mcp-server
npm install
npm run build

# Authenticate with Sprite
sprite login
# or
sprite auth setup --token "your-token"

# Test
sprite list

Claude Desktop Configuration

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "sprite": {
      "command": "node",
      "args": ["/path/to/sprite-mcp-server/dist/index.js"],
      "env": {
        "SPRITE_BIN": "/home/youruser/.local/bin/sprite"
      }
    }
  }
}

Claude Code Configuration

claude mcp add sprite -- node /path/to/sprite-mcp-server/dist/index.js

Server Deployment (for Claude.ai web)

For hosting your own MCP server accessible from claude.ai:

Prerequisites

Node.js 20+
A domain pointing to your server (for HTTPS)
Caddy or nginx for reverse proxy

Deploy

# Clone & build
git clone https://github.com/Anansitrading/sprite-mcp-server.git
cd sprite-mcp-server
npm install
npm run build

# Configure
cp .env.example .env
# Edit .env:
#   PORT=3847
#   SPRITE_BIN=/home/sprite/.local/bin/sprite

# Run with systemd
sudo cp sprite-mcp.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable sprite-mcp
sudo systemctl start sprite-mcp

Caddy Reverse Proxy

mcp.yourdomain.com {
    reverse_proxy localhost:3847
}

Connect to Claude.ai

Go to claude.ai/settings/integrations
Add MCP Server:
- Name: sprite-mcp
- URL: https://mcp.yourdomain.com/sse
Test by asking Claude: "List my sprites"

MCP Tools

Tool	Description
`list_sprites`	List all Sprite VMs (with interactive dashboard)
`exec_command`	Execute command on a sprite (with terminal UI)
`create_checkpoint`	Create filesystem snapshot
`list_checkpoints`	List available checkpoints
`restore_checkpoint`	Restore to a checkpoint
`get_sprite_url`	Get sprite's public URL
`fetch_file`	Download file from sprite
`push_file`	Upload file to sprite
`list_sessions`	List active sessions
`create_sprite`	Create new sprite VM
`destroy_sprite`	Delete a sprite VM

Interactive UIs (MCP Apps)

This server uses MCP Apps to provide interactive interfaces:

Dashboard (ui://sprite/dashboard) - Visual sprite management
Terminal (ui://sprite/terminal) - Command execution interface

These render directly in the Claude conversation when using supported clients.

Troubleshooting

Windows: "sprite is not recognized"

Add Sprite to your PATH or use the full path in SPRITE_BIN:

# Find sprite location
where sprite

# Add to PATH (PowerShell, run as admin)
$env:Path += ";C:\Users\YourName\.local\bin"
[Environment]::SetEnvironmentVariable("Path", $env:Path, [EnvironmentVariableTarget]::User)

Windows: "ENOENT" or "spawn error"

Ensure all paths use double backslashes or forward slashes
Verify the dist/index.js file exists (run npm run build first)
Check that SPRITE_BIN points to the actual .exe file

"Sprite CLI not authenticated"

# Re-authenticate
sprite login

# Or with token
sprite auth setup --token "your-token"

# Verify
sprite list

Check server health

# If running HTTP server
curl http://localhost:3847/health

Test MCP handshake

echo '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}' | npm start

Architecture

┌─────────────────────────────────────────────────────────┐
│                    Claude.ai / Desktop                   │
├─────────────────────────────────────────────────────────┤
│                    MCP Protocol                          │
│              (stdio or HTTP/SSE transport)               │
├─────────────────────────────────────────────────────────┤
│                  sprite-mcp-server                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐  │
│  │ MCP Tools   │  │ UI Resources│  │ Sprite CLI      │  │
│  │ (11 tools)  │  │ (Dashboard) │  │ Integration     │  │
│  └─────────────┘  └─────────────┘  └─────────────────┘  │
├─────────────────────────────────────────────────────────┤
│                    Sprite CLI                            │
│              (sprite list, exec, checkpoint...)          │
├─────────────────────────────────────────────────────────┤
│                 Sprites API / VMs                        │
└─────────────────────────────────────────────────────────┘

License

MIT