Overview

WaveSpeed MCP Server is a lightweight Model Context Protocol (MCP) server that exposes AI image and video generation capabilities to agents and applications. It provides a consistent, tool-oriented interface for creating, editing, and streaming media artifacts (images, animations, short videos) so agents can integrate visual generation into multi-step workflows without embedding model details.

The server is designed for low-latency and scalable deployment: it can run locally for development or be deployed on GPU-enabled infrastructure, and supports batched requests, streaming outputs, and configurable storage backends. For developers building agent-driven pipelines, WaveSpeed simplifies orchestration of prompts, assets, and post-processing through a small set of well-defined tools and endpoints.

Features

Tool-oriented MCP interface for image and video generation
Support for image generation, inpainting, upscaling, and video/animation synthesis
Streaming responses for progressive image/video frames or status updates
Batched requests and concurrency controls for throughput tuning
Pluggable storage backends (local disk, S3-compatible) for artifacts
Authentication and rate-limiting hooks for production deployments
Configuration via environment variables and a YAML/JSON config file
Docker-ready and GPU-friendly deployment options

Installation / Configuration

Quickstart using Docker:

# Pull and run a prebuilt WaveSpeed MCP Server image
docker pull wavespeedai/mcp-server:latest
docker run -d --name wavespeed-mcp \
  -p 8080:8080 \
  -e MCP_BIND=0.0.0.0:8080 \
  -e STORAGE_PATH=/data/wavespeed \
  -v $(pwd)/data:/data/wavespeed \
  wavespeedai/mcp-server:latest

Environment variables (examples):

# Network
MCP_BIND=0.0.0.0:8080

# Storage
STORAGE_BACKEND=local         # or s3
STORAGE_PATH=/data/wavespeed

# Performance
MAX_WORKERS=4
BATCH_SIZE=8

# Security
API_KEY=your_api_key_here

# Model / runtime specific
ENABLE_GPU=true

YAML configuration sample (config.yaml):

server:
  bind: "0.0.0.0:8080"
storage:
  backend: "local"
  path: "/data/wavespeed"
runtime:
  enable_gpu: true
  max_workers: 4
  batch_size: 8
security:
  api_key: "your_api_key_here"

Start with a config file:

./mcp-server --config config.yaml

Or run from source (typical Node/Python startup):

git clone https://github.com/WaveSpeedAI/mcp-server.git
cd mcp-server
# Follow repository README for language-specific start steps

Available Tools / Resources

The server exposes a small set of MCP tools (HTTP endpoints) that agents can call. Typical tool names and capabilities:

Tool name	Purpose	Key params
image_generator	Create images from text prompts	prompt, width, height, steps, seed
image_inpaint	Edit regions of an image using mask + prompt	image_id, mask, prompt
image_upscale	Increase resolution of an existing image	image_id, scale (2x/4x)
video_generator	Synthesize short videos or animated frames	prompt, duration_sec, fps, resolution
stream_tool	Stream frames/status updates	session_id, format (jpeg/mp4/frames)

Each tool follows MCP conventions: agents receive tool metadata, invoke the tool with parameters, and get back either a synchronous response (URL/ID) or a streaming response (progress + partial frames).

APIs are typically available under /v1/, for example:

POST /v1/tools/image_generator
POST /v1/tools/image_inpaint
POST /v1/tools/video_generator
GET /v1/artifacts/{artifact_id}
WS /v1/stream/{session_id}

Authentication is token-based (via X-API-Key header or Authorization: Bearer) and storage-backed artifact URLs can be pre-signed for client downloads.

Use Cases

Agent-driven content creation: An AI assistant composes a prompt and calls image_generator to produce illustrations for a generated article, then uses image_upscale for final delivery.
Automated thumbnail & preview generation: A media pipeline generates thumbnails and short preview clips from textual descriptions or storyboard prompts for a large catalog.
Synthetic data generation: Create varied labeled images or short videos as training data by combining prompt templates and batch requests.
Interactive editing agents: Use image_inpaint to let agents iteratively refine an image based on user edits, streaming intermediate frames during refinement.
Rapid prototyping: Designers and developers can quickly generate mockups, storyboards, or animated prototypes without manually operating multiple model backends.

Examples

Curl example — generate an image:

curl -X POST "http://localhost:8080/v1/tools/image_generator" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${API_KEY}" \
  -d '{
    "prompt": "A futuristic city skyline at sunset, cinematic lighting",
    "width": 1024,
    "height": 576,
    "steps": 30
  }'

Python example — download artifact:

import requests

resp = requests.post(
    "http://localhost:8080/v1/tools/image_generator",
    json={"prompt":"Minimal product mockup, white background", "width":512, "height":512},
    headers={"Authorization":"Bearer "+API_KEY},
)
data = resp.json()
artifact_url = data["artifact_url"]

r = requests.get(artifact_url)
with open("output.png", "wb") as f:
    f.write(r.content)

Further Resources

Source code and issues: https://github.com/WaveSpeedAI/mcp-server
Typical MCP specification: consult your agent framework docs for tool registration and interaction patterns
Deployment tips: enable GPU runtime, tune MAX_WORKERS and BATCH_SIZE for throughput, and use S3 for scalable storage

This documentation provides a starting point for integrating WaveSpeed MCP Server into agent-based systems and media pipelines. For advanced configuration and model-specific options, refer to the repository’s README and configuration reference.

WaveSpeed MCP Server: AI Image & Video Generation