Sprite MCP Server

How to use

You will connect your MCP client to the server to access an interactive dashboard and command interfaces. Use the HTTP/SSE channel for Claude.ai interactions and the local stdio channel for direct CLI-based usage. From the interactive dashboard you can list and manage Sprite VMs, execute commands in a terminal-like interface, create and restore filesystem checkpoints, transfer files to and from sprites, and manage sessions. When you attach to a sprite session, you can run commands, view output, and keep a history of commands for reuse.

How to install

Prerequisites required before installation include Node.js 20 or newer, a domain pointing to your server for HTTPS, and the Sprite CLI configured with credentials.

# 1. Clone and install
git clone https://github.com/davidkiama/sprite-mcp-server.git
cd sprite-mcp-server
npm install
npm run build

# 2. Configure environment
cp .env.example .env
# Edit .env with your settings
```

```env
PORT=3847
SPRITE_BIN=/path/to/sprite  # Usually ~/.local/bin/sprite
```

```bash
# 3. Run with systemd (recommended)

# Copy service file
sudo cp sprite-mcp.service /etc/systemd/system/

# Edit the service file to set your paths
sudo nano /etc/systemd/system/sprite-mcp.service

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable sprite-mcp
sudo systemctl start sprite-mcp

# Check status
sudo systemctl status sprite-mcp
```

```bash
# 4. Set Up Reverse Proxy (Caddy)

# Install Caddy if needed
sudo apt install -y caddy

# Add to /etc/caddy/Caddyfile
echo '\nmcp.yourdomain.com {
    reverse_proxy localhost:3847
}
' | sudo tee -a /etc/caddy/Caddyfile

# Reload Caddy
sudo systemctl reload caddy
```

```bash
# 5. Connect to Claude.ai

1. Go to 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
```

```bash
# 6. Local Development

# Run stdio server (for Claude Code/Desktop)
npm start

# Run HTTP/SSE server (for claude.ai)
npm run start:http

# Development mode with hot reload
npm run dev
```]} ,{

How to install

Prerequisites required before installation include Node.js 20 or newer, a domain pointing to your server for HTTPS, and the Sprite CLI configured with credentials.

# 1. Clone and install
git clone https://github.com/davidkiama/sprite-mcp-server.git
cd sprite-mcp-server
npm install
npm run build

# 2. Configure environment
cp .env.example .env
# Edit .env with your settings
```

```env
PORT=3847
SPRITE_BIN=/path/to/sprite  # Usually ~/.local/bin/sprite
```

```bash
# 3. Run with systemd (recommended)

# Copy service file
sudo cp sprite-mcp.service /etc/systemd/system/

# Edit the service file to set your paths
sudo nano /etc/systemd/system/sprite-mcp.service

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable sprite-mcp
sudo systemctl start sprite-mcp

# Check status
sudo systemctl status sprite-mcp
```

```bash
# 4. Set Up Reverse Proxy (Caddy)

# Install Caddy if needed
sudo apt install -y caddy

# Add to /etc/caddy/Caddyfile
echo '\nmcp.yourdomain.com {
    reverse_proxy localhost:3847
}
' | sudo tee -a /etc/caddy/Caddyfile

# Reload Caddy
sudo systemctl reload caddy
```

```bash
# 5. Connect to Claude.ai

1. Go to 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
```

```bash
# 6. Local Development

# Run stdio server (for Claude Code/Desktop)
npm start

# Run HTTP/SSE server (for claude.ai)
npm run start:http

# Development mode with hot reload
npm run dev
```} ,{

Interactive UIs (MCP Apps)

This server uses MCP Apps to provide interactive interfaces that render inside supported clients. The Dashboard gives a visual interface for sprite management, while the Terminal provides a command execution interface.

Architecture

A schematic overview shows Claude.ai or Desktop interacting with the MCP Protocol over stdio or HTTP/SSE transport, connected to the sprite-mcp-server, which coordinates MCP Tools, UI Resources, and Sprite CLI integrations to manage the Sprites and their VMs.

Troubleshooting

Check if the server is running by querying the health endpoint. If you are using systemd, inspect logs with journalctl. For local runs, redirect logs to a file to diagnose startup issues.

Configuration notes

The server relies on a local environment file to configure runtime paths and ports. Ensure PORT is set to the desired public port and SPRITE_BIN points to your installed Sprite CLI binary. When running behind a reverse proxy, expose the MCP endpoint via the proxy to your clients.

Security considerations

Use HTTPS via a domain you control. Restrict access to MCP endpoints as appropriate for your environment, and rotate credentials for the Sprite CLI integration periodically. Regularly monitor the MCP server logs for unusual activity.

list_sprites

List all Sprite VMs with an interactive dashboard.

exec_command

Execute a command on a sprite through a terminal interface.

create_checkpoint

Create a filesystem checkpoint for a sprite.

list_checkpoints

List available checkpoints for sprites.

restore_checkpoint

Restore a sprite to a selected checkpoint.

get_sprite_url

Get the public URL for a sprite.

fetch_file

Download a file from a sprite.

push_file

Upload a file to a sprite.

list_sessions

List active sessions.

create_sprite

Create a new sprite VM.

destroy_sprite

Delete a sprite VM.