# 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](https://nodejs.org/)
- **Git** - Download from [git-scm.com](https://git-scm.com/download/win)
- **Sprite CLI** - Get your token from [sprites.dev](https://sprites.dev)
### Step 1: Install Sprite CLI
Download and install the Sprite CLI for Windows:
```powershell
# Using PowerShell (run as Administrator)
irm https://sprites.dev/install.ps1 | iex
```
Or download manually from [sprites.dev/downloads](https://sprites.dev/downloads).
### Step 2: Authenticate with Sprite
Get your API token from the Sprites dashboard, then:
```powershell
# 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:
```powershell
sprite list
```
### Step 3: Clone and Build the MCP Server
```powershell
# 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
```powershell
# 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:
```powershell
notepad "$env:APPDATA\Claude\claude_desktop_config.json"
```
Add this configuration (replace paths with your actual paths):
```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"
}
}
}
}
```
**Important:** Use double backslashes (`\\`) in paths or forward slashes (`/`).
### Step 6: Restart Claude Desktop
1. Fully quit Claude Desktop (check system tray)
2. Reopen Claude Desktop
3. 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:
```powershell
# Open Claude Code settings
claude mcp add sprite -- node "C:\Users\YourName\sprite-mcp-server\dist\index.js"
```
Or edit `~/.claude/settings.json`:
```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
```bash
# 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`
```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
```bash
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
```bash
# 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
```caddyfile
mcp.yourdomain.com {
reverse_proxy localhost:3847
}
```
### Connect to Claude.ai
1. Go to [claude.ai/settings/integrations](https://claude.ai/settings/integrations)
2. Add MCP Server:
- **Name**: `sprite-mcp`
- **URL**: `https://mcp.yourdomain.com/sse`
3. 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`:
```powershell
# 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"
```bash
# Re-authenticate
sprite login
# Or with token
sprite auth setup --token "your-token"
# Verify
sprite list
```
### Check server health
```bash
# If running HTTP server
curl http://localhost:3847/health
```
### Test MCP handshake
```bash
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
