sproto-studio-mcp

v2.2.0

Published

2 months ago

MCP server for Sproto Studio — AI image, video, music, 3D, and avatar generation, payable per-call via x402 USDC on Base. Works with Claude Desktop, Cursor, VS Code, ChatGPT, and any MCP-compatible host.

Downloads

Sproto Studio MCP Server v2.2.0

A comprehensive MCP server with interactive UI powered by the MCP Apps extension (SEP-1865). Tools return rich, interactive interfaces rendered as sandboxed iframes inside Claude Desktop, ChatGPT, Cursor, VS Code, Goose, and any MCP Apps-compatible host.

🔒 SECURITY UPDATE v2.1.0 - UPDATE REQUIRED Critical security vulnerabilities have been fixed in this version:
Fixed: Command injection vulnerabilities in FFmpeg and Blender operations
Fixed: Path traversal vulnerability in file operations
Added: File size limits (500MB max) and URL validation
Added: Content-type validation for downloads
Added: Request timeouts (60s) to prevent DoS
⚠️ MANDATORY UPDATE: Versions prior to v2.1.0 are now blocked by the API. Old versions will receive a 426 Upgrade Required error with update instructions.
cd mcp-server
git pull
npm install
# Restart your MCP client (Claude Desktop, Cursor, etc.)

Features

Image Generation - Create images with Sproto style presets using Nano Banana Pro
Video Generation - Generate videos with Veo 3 (fast and high quality modes)
Gameplay Shorts - Trim local gameplay clips, burn timed captions, add AI voiceover, and export ready-to-post Shorts
Music Generation - Create songs with Sprotify (Suno V5) with mood presets
3D Asset Generation - Convert images to 3D models using Hunyuan3D
Episode Director - Create multi-scene episodes with Director AI
Retain Tracker - Track your discipline streak and report progress
NFT Collections - Search curated Sprollection archives
Talking Sprotos - Post messages as Sproto characters
Sproto Lab - Submit community apps

Quick Start

1. Get an MCP Token

Go to your Sproto Studio Profile and navigate to the API tab. Create a new MCP token.

2. Install Dependencies

cd mcp-server
npm install

3. Set Your Token

export SPROTO_API_TOKEN=sproto_mcp_v1_xxxxx

4. Build the Interactive UI

npm run build:ui

5. Run the Server

# Classic MCP server (text-only, works everywhere):
npm start

# MCP Apps server (interactive UI in supported hosts):
npm run start:apps

Integration

Claude Desktop (with MCP Apps UI)

Add to your Claude Desktop config:

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "sproto-studio": {
      "command": "npx",
      "args": ["tsx", "/path/to/sprotostudio/mcp-server/apps-server.ts"],
      "env": {
        "SPROTO_API_TOKEN": "sproto_mcp_v1_xxxxx"
      }
    }
  }
}

Tools will render interactive React UIs directly inside the chat when supported by the host. Falls back to plain text on clients without MCP Apps support.

Classic MCP (text-only, any client)

{
  "mcpServers": {
    "sproto-studio": {
      "command": "npx",
      "args": ["tsx", "/path/to/sprotostudio/mcp-server/index.ts"],
      "env": {
        "SPROTO_API_TOKEN": "sproto_mcp_v1_xxxxx"
      }
    }
  }
}

Cursor / VS Code / ChatGPT / Goose

All use the same config format. Point to apps-server.ts for interactive UI or index.ts for text-only.

Available Tools

Generation Tools

| Tool | Description | Credits | |------|-------------|---------| | sproto_generate_image | Generate AI images with Sproto style | 20 (~$0.30) | | sproto_generate_video | Generate videos with Veo 3 | 80-400 (~$1.20-$6.00) | | sproto_create_gameplay_short | Trim gameplay clips into a Short with timed captions and optional Gemini voiceover | Local FFmpeg | | sproto_generate_music | Create music with Suno V5 | 60 (~$0.90) | | sproto_generate_3d_asset | Convert images to 3D | 100-150 (~$1.50-$2.25) | | sproto_create_episode | Create multi-scene episodes | 200 (~$3.00) |

Data & Query Tools

| Tool | Description | |------|-------------| | sproto_get_credits | Check credit balance and costs | | sproto_get_status | Check generation task progress | | sproto_get_sproto | Get a Sproto reference image by ID | | sproto_list_characters | Browse Sprotos and Talking Sprotos | | sproto_get_presets | Get style presets and templates | | sproto_get_retain_score | Check your Retain streak | | sproto_search_collections | Search NFT collections |

Action Tools

| Tool | Description | |------|-------------| | sproto_checkin_retain | Daily Retain check-in | | sproto_report_coom | Report a relapse (resets streak) | | sproto_post_message | Post as a Talking Sproto | | sproto_submit_app | Submit app to Sproto Lab |

Example Usage

Generate an Image

"Generate an image of Sproto 2301 surfing a giant wave at sunset"

Response:

{
  "success": true,
  "taskId": "task_abc123",
  "type": "image",
  "creditsCharged": 20,
  "newBalance": 480,
  "message": "Image generation started. Use sproto_get_status with taskId to check progress."
}

Create an Episode

"Create a cartoon episode about Sproto 420 going on a space adventure"

Response:

{
  "success": true,
  "episodeId": "ep_xyz789",
  "title": "Sproto 420's Cosmic Journey",
  "sceneCount": 5,
  "viewUrl": "https://sproto.studio/episodes/ep_xyz789"
}

Check Your Credits

"What's my current credit balance?"

Response:

{
  "success": true,
  "credits": {
    "balance": 500,
    "totalSpent": 1200,
    "totalPurchased": 1700
  },
  "costs": {
    "image": 20,
    "videoFast": 80,
    "videoQuality": 400,
    "music": 60,
    "asset3dDirect": 100
  }
}

Generate Music

"Create a chill lo-fi track called 'Sproto Vibes' about relaxing in the digital realm"

Response:

{
  "success": true,
  "taskId": "music_def456",
  "type": "music",
  "creditsCharged": 60,
  "message": "Music generation started. Use sproto_get_status to check progress."
}

Summon a Sproto

"Get me Sproto #420 for reference"

Response:

{
  "success": true,
  "sproto": {
    "id": 420,
    "name": "Sproto #420",
    "imageUrl": "https://bafybeiefzvptnmjns6mq37wgey3hhh5hth7vznnrdrv2km6nkhvs23kthq.ipfs.dweb.link/420.png"
  }
}

Check Retain Score

"What's my current Retain streak?"

Response:

{
  "success": true,
  "retain": {
    "currentStreak": 15,
    "bestStreak": 30,
    "totalDays": 45,
    "coomCount": 2,
    "lastCheckin": "2026-01-13T08:00:00Z"
  }
}

Style Presets

Scene Templates

action-chase - High-energy chase scene
chill-hangout - Relaxed conversation
beach-party - Fun celebration
space-adventure - Cosmic journey
epic-battle - Intense showdown

Music Moods

energy - High-energy EDM
chill - Lo-fi chillwave
sunny - Upbeat indie pop
midnight - Dark wave
fire - Aggressive phonk
golden - Nostalgic synthwave

Episode Modes

default - Standard Sproto style
basemode - Base chain aesthetic
trailer - Cinematic trailer style
lore - Deep lore exploration
sprokemon - Pokemon-inspired

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | SPROTO_API_TOKEN | Your MCP API token (required) | - | | SPROTO_STUDIO_API | API base URL | https://sproto.studio |

Credits System

All generation tools use credits. Check your balance with sproto_get_credits.

Credit Packs:

Starter: 333 credits / $5
Pro: 1,333 credits / $20
Studio: 3,333 credits / $50

Buy credits at sproto.studio/credits

Token Management

Manage your MCP tokens at your Sproto Studio Profile in the API tab.

Create multiple tokens for different integrations
View last used timestamps
Revoke tokens at any time
Tokens never expire unless you set an expiration

Troubleshooting

"SPROTO_API_TOKEN not set"

Make sure you've set the environment variable or included it in your MCP config.

"Invalid or expired API token"

Generate a new token at sproto.studio/profile.

"Insufficient credits"

Buy more credits at sproto.studio/credits.

"Permission denied"

Your token may have restricted permissions. Create a new token with full access.

Changelog

v2.2.0 (2026-01-27) - MCP Apps Interactive UI

MCP Apps Extension (SEP-1865):

Added apps-server.ts — MCP Apps server with interactive ui:// resources
Tools now declare _meta.ui.resourceUri pointing to bundled React UIs
Interactive iframe renders inside Claude Desktop, ChatGPT, Cursor, VS Code, Goose
Rich result visualization: credit dashboards, generation progress, character galleries
Bidirectional communication: re-invoke tools, send messages to model from the UI
Uses @modelcontextprotocol/ext-apps SDK with useApp() React hook
Vite single-file bundling for self-contained HTML resources
Falls back to inline HTML when pre-built bundles aren't available

New Scripts:

npm run start:apps — Launch the MCP Apps server
npm run build:ui — Build React UI into single-file HTML
npm run dev:apps — Development mode for apps server

New Dependencies:

@modelcontextprotocol/ext-apps — MCP Apps SDK
react / react-dom — Interactive UI framework
vite + vite-plugin-singlefile — Single-file HTML bundling

v2.1.0 (2026-01-19) - Security Hardening Release

Security Fixes:

🔒 Fixed command injection vulnerability in FFmpeg operations
🔒 Fixed command injection vulnerability in Blender optimizer
🔒 Fixed path traversal vulnerability in media stitching
🔒 Added file size limits (500MB max) to prevent DoS
🔒 Added URL validation (HTTP/HTTPS only)
🔒 Added content-type validation for downloads
🔒 Added request timeouts (60s) to prevent hangs

Version Enforcement:

🚫 API now blocks versions < 2.1.0 (returns 426 Upgrade Required)
✅ MCP server now sends version header with all requests
⚠️ Old versions will stop working immediately upon API deployment

Context Optimization:

📉 Reduced tool descriptions by ~70% to save context window
📚 Moved detailed docs to TOOLS.md reference

Breaking Changes: None for updated clients - fully backward compatible with v2.1.0+

Upgrade Instructions:

cd mcp-server
git pull
npm install
# Restart your MCP server (Claude Desktop, etc.)

v2.0.0 (2026-01-15)

Initial MCP server release
Full Sproto Studio API integration
Support for image, video, music, 3D generation
Roblox integration tools

Support

GitHub Issues: github.com/psychedelanon/sprotostudio/issues
Warpcast: @sprotostudio

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Sproto Studio MCP Server v2.2.0

Features

Quick Start

1. Get an MCP Token

2. Install Dependencies

3. Set Your Token

4. Build the Interactive UI

5. Run the Server

Integration

Claude Desktop (with MCP Apps UI)

Classic MCP (text-only, any client)

Cursor / VS Code / ChatGPT / Goose

Available Tools

Generation Tools

Data & Query Tools

Action Tools

Example Usage

Generate an Image

Create an Episode

Check Your Credits

Generate Music

Summon a Sproto

Check Retain Score

Style Presets

Scene Templates

Music Moods

Episode Modes

Environment Variables

Credits System

Token Management

Troubleshooting

"SPROTO_API_TOKEN not set"

"Invalid or expired API token"

"Insufficient credits"

"Permission denied"

Changelog

v2.2.0 (2026-01-27) - MCP Apps Interactive UI

v2.1.0 (2026-01-19) - Security Hardening Release

v2.0.0 (2026-01-15)

Support

License