WavespeedMCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@WavespeedMCP Generate an image of a futuristic cityscape at night"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
WavespeedMCP
English | 中文文档
WavespeedMCP is a Model Control Protocol (MCP) server implementation for WaveSpeed AI services. It provides a standardized interface for accessing WaveSpeed's image and video generation capabilities through the MCP protocol.
Related MCP server: image-forge-mcp
Features
Advanced Image Generation: Create high-quality images from text prompts with support for image-to-image generation, inpainting, and LoRA models
Dynamic Video Generation: Transform static images into videos with customizable motion parameters
Optimized Performance: Enhanced API polling with intelligent retry logic and detailed progress tracking
Flexible Resource Handling: Support for URL, Base64, and local file output modes
Comprehensive Error Handling: Specialized exception hierarchy for precise error identification and recovery
Robust Logging: Detailed logging system for monitoring and debugging
Multiple Configuration Options: Support for environment variables, command-line arguments, and configuration files
Installation
Prerequisites
Python 3.11+
WaveSpeed API key (obtain from WaveSpeed AI)
Setup
Install directly from PyPI:
pip install wavespeed-mcpMCP Configuration
To use WavespeedMCP with your IDE or application, add the following configuration:
{
"mcpServers": {
"WaveSpeed": {
"command": "wavespeed-mcp",
"env": {
"WAVESPEED_API_KEY": "your-api-key-here",
"WAVESPEED_LOG_FILE": "/tmp/wavespeed-mcp.log"
}
}
}
}Usage
Running the Server
Start the WavespeedMCP server:
wavespeed-mcp --api-key your_api_key_hereClaude Desktop Integration
WavespeedMCP can be integrated with Claude Desktop. To generate the necessary configuration file:
python -m wavespeed_mcp --api-key your_api_key_here --config-path /path/to/claude/configThis command generates a claude_desktop_config.json file that configures Claude Desktop to use WavespeedMCP tools. After generating the configuration:
Start the WavespeedMCP server using the
wavespeed-mcpcommandLaunch Claude Desktop, which will use the configured WavespeedMCP tools
Configuration Options
WavespeedMCP can be configured through:
Environment Variables:
WAVESPEED_API_KEY: Your WaveSpeed API key (required)WAVESPEED_API_HOST: API host URL (default: https://api.wavespeed.ai)WAVESPEED_MCP_BASE_PATH: Base path for saving generated files (default: ~/Desktop)WAVESPEED_API_RESOURCE_MODE: Resource output mode -url,local, orbase64(default: url)WAVESPEED_LOG_LEVEL: Logging level - DEBUG, INFO, WARNING, ERROR (default: INFO)WAVESPEED_LOG_FILE: Optional log file path (if not set, logs to console)WAVESPEED_API_TEXT_TO_IMAGE_ENDPOINT: Custom endpoint for text-to-image generation (default: /wavespeed-ai/flux-dev)WAVESPEED_API_IMAGE_TO_IMAGE_ENDPOINT: Custom endpoint for image-to-image generation (default: /wavespeed-ai/flux-kontext-pro)WAVESPEED_API_VIDEO_ENDPOINT: Custom endpoint for video generation (default: /wavespeed-ai/wan-2.1/i2v-480p-lora)
Timeouts
WavespeedMCP supports two types of timeouts. Configure them via environment variables:
WAVESPEED_REQUEST_TIMEOUT: Per-HTTP request timeout in seconds (default: 300 = 5 minutes). This applies to individual HTTP calls made by the client, such as submitting a job or downloading outputs.WAVESPEED_WAIT_RESULT_TIMEOUT: Total timeout for waiting/polling results in seconds (default: 600 = 10 minutes). This limits the overall time spent polling for an asynchronous job result. When exceeded, polling stops with a timeout error.
Example:
export WAVESPEED_REQUEST_TIMEOUT=300 # per HTTP request
export WAVESPEED_WAIT_RESULT_TIMEOUT=900 # total wait for result (polling)Logging Configuration
By default, the MCP server logs to console. You can configure file logging by setting the WAVESPEED_LOG_FILE environment variable:
# Log to /tmp directory
export WAVESPEED_LOG_FILE=/tmp/wavespeed-mcp.log
# Log to system log directory
export WAVESPEED_LOG_FILE=/var/log/wavespeed-mcp.log
# Log to user home directory
export WAVESPEED_LOG_FILE=~/logs/wavespeed-mcp.logThe log file uses rotating file handler with:
Maximum file size: 10MB
Backup count: 5 files
Log format:
%(asctime)s - wavespeed-mcp - %(levelname)s - %(message)s
Command-line Arguments:
--api-key: Your WaveSpeed API key--api-host: API host URL--config: Path to configuration file
Configuration File (JSON format): See
wavespeed_mcp_config_demo.jsonfor an example.
Architecture
WavespeedMCP follows a clean, modular architecture:
server.py: Core MCP server implementation with tool definitionsclient.py: Optimized API client with intelligent pollingutils.py: Comprehensive utility functions for resource handlingexceptions.py: Specialized exception hierarchy for error handlingconst.py: Constants and default configuration values
Development
Requirements
Python 3.11+
Development dependencies:
pip install -e ".[dev]"
Testing
Run the test suite:
pytestOr with coverage reporting:
pytest --cov=wavespeed_mcpLicense
This project is licensed under the MIT License - see the LICENSE file for details.
Support
For support or feature requests, please contact the WaveSpeed AI team at support@wavespeed.ai.
Available Tools
3 toolsgenerate_videoA
Generate a video using WaveSpeed AI.
Args:
image (str): Required. URL, base64 string, or local file path of the input image to animate.
prompt (str): Required. Text description of the video to generate. MUST BE IN ENGLISH. Non-English prompts will be rejected or result in poor quality outputs.
model (str, optional): Model to use for video generation.
negative_prompt (str, optional): Text description of what to avoid in the video. Default: "".
loras (list, optional): List of LoRA models to use, each with a path and scale. Format: [{"path": "model_path", "scale": weight_value}]. Default: [].
size (str, optional): Size of the output video in format "width*height". Default: "832*480".
num_inference_steps (int, optional): Number of denoising steps. Higher values improve quality but increase generation time. Default: 30.
duration (int, optional): Duration of the video in seconds. Must be either 5 or 10. Default: 5.
guidance_scale (float, optional): Guidance scale for text adherence. Controls how closely the video matches the text description. Default: 5.
flow_shift (int, optional): Shift of the flow in the video. Affects motion intensity. Default: 3.
seed (int, optional): Random seed for reproducible results. Set to -1 for random. Default: -1.
enable_safety_checker (bool, optional): Whether to enable safety filtering. Default: True.
output_directory (str, optional): Directory to save the generated video. Uses a temporary directory if not provided.
request_id (str, optional): Request correlation ID for tracing the entire request chain. Strongly recommended to provide a unique ID (e.g., UUID) to correlate logs across the request lifecycle.
Returns:
WaveSpeedResult object with the result of the video generation, containing:
- status: "success" or "error"
- urls: List of video URLs if successful
- base64: List of base64 encoded videos if resource_mode is set to base64
- local_files: List of local file paths if resource_mode is set to local
- error: Error message if status is "error"
- processing_time: Time taken to generate the video(s)
Examples:
Basic usage: generate_video(image="https://example.com/image.jpg", prompt="The dog running through a forest")
Advanced usage: generate_video(
image="/path/to/local/image.jpg",
prompt="The dog running through a forest",
duration=10,
negative_prompt="blurry, low quality"
)
Note:
IMPORTANT: Prompts MUST be in English. The system only processes English prompts properly.
Non-English prompts will be rejected or produce low-quality results. If user input is not in English,
you MUST translate it to English before passing to this tool.
Inputs: image (required), prompt (required), model, negative_prompt, +10 more.
image_to_imageA
Generate an image from an existing image using WaveSpeed AI.
Args:
image (str): Required. URL, base64 string, or local file path of the input image to modify.
images (List[str]): Required. List of URLs to images to modify.
prompt (str): Required. Text description of the desired modifications. MUST BE IN ENGLISH. Non-English prompts will be rejected or result in poor quality outputs.
model (str, optional): Model to use for image generation.
guidance_scale (float, optional): Guidance scale for text adherence. Controls how closely the output follows the prompt. Range: [1.0-10.0]. Default: 3.5.
enable_safety_checker (bool, optional): Whether to enable safety filtering. Default: True.
output_directory (str, optional): Directory to save the generated images. Uses a temporary directory if not provided.
request_id (str, optional): Request correlation ID for tracing the entire request chain. Strongly recommended to provide a unique ID (e.g., UUID) to correlate logs across the request lifecycle.
Returns:
WaveSpeedResult object with the result of the image generation, containing:
- status: "success" or "error"
- urls: List of image URLs if successful
- base64: List of base64 encoded images if resource_mode is set to base64
- local_files: List of local file paths if resource_mode is set to local
- error: Error message if status is "error"
- processing_time: Time taken to generate the image(s)
Examples:
Single image: image_to_image(image="https://example.com/image.jpg", images=[], prompt="Make it look like winter")
Multiple images: image_to_image(image="", images=["https://example.com/img1.jpg", "https://example.com/img2.jpg"], prompt="Convert to oil painting style")
Both parameters: image_to_image(image="https://example.com/main.jpg", images=["https://example.com/ref1.jpg"], prompt="Apply style transfer")
Note:
For optimal results, always provide prompts in English, regardless of your interface language.
Non-English prompts may result in lower quality or unexpected images.
Inputs: image (required), images (required), prompt (required), model, +4 more.
text_to_imageA
Generate an image from text prompt using WaveSpeed AI.
Args:
prompt (str): Required. Text description of the image to generate. MUST BE IN ENGLISH. Non-English prompts will be rejected or result in poor quality outputs.
model (str, optional): Model to use for image generation.
loras (list, optional): List of LoRA models to use, each with a path and scale. Format: [{"path": "model_path", "scale": weight_value}]. Default model used if not provided.
size (str, optional): Size of the output image in format "width*height", e.g., "512*512". Default: 1024*1024.
num_inference_steps (int, optional): Number of denoising steps. Higher values improve quality but increase generation time. Default: 30.
guidance_scale (float, optional): Guidance scale for text adherence. Controls how closely the image matches the text description. Default: 7.5.
num_images (int, optional): Number of images to generate. Default: 1.
seed (int, optional): Random seed for reproducible results. Set to -1 for random. Default: -1.
enable_safety_checker (bool, optional): Whether to enable safety filtering. Default: True.
output_directory (str, optional): Directory to save the generated images. Uses a temporary directory if not provided.
request_id (str, optional): Request correlation ID for tracing the entire request chain. Strongly recommended to provide a unique ID (e.g., UUID) to correlate logs across the request lifecycle.
Returns:
WaveSpeedResult object with the result of the image generation, containing:
- status: "success" or "error"
- urls: List of image URLs if successful
- base64: List of base64 encoded images if resource_mode is set to base64
- local_files: List of local file paths if resource_mode is set to local
- error: Error message if status is "error"
- processing_time: Time taken to generate the image(s)
Examples:
Basic usage: text_to_image(prompt="A golden retriever running on grass")
Advanced usage: text_to_image(
prompt="A golden retriever running on grass",
size="1024*1024",
num_inference_steps=50,
seed=42
)
Note:
For optimal results, always provide prompts in English, regardless of your interface language.
Non-English prompts may result in lower quality or unexpected images.
Inputs: prompt (required), model, loras, size, +7 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a clearly distinct purpose: generate_video for video from an image, image_to_image for modifying images, and text_to_image for generating images from text. There is no ambiguity or overlap.
Tool names follow a relatively consistent lowercase snake_case pattern, but the structure varies: 'generate_video' is verb_noun, while 'image_to_image' and 'text_to_image' are noun_to_noun. This slight inconsistency is not confusing.
With only 3 tools, the server covers basic media generation but feels minimal. The scope could warrant additional tools like model listing or result retrieval, but the count is not extreme.
The server lacks essential operations for a media generation domain, such as model management, result status, or video-to-video generation. Users will encounter gaps in common workflows.
Related MCP Connectors
MCP server for Wan AI video generation
MCP server for Qwen Image 3 AI image generation
MCP server for Google Veo AI video generation
Stivio MCP server - AI image-to-video generator via MCP.
Related MCP Servers
AlicenseAqualityBmaintenanceProvides a standardized interface for accessing WaveSpeed's image and video generation capabilities through the MCP protocol.72,304 npm37MIT- FlicenseNot gradedqualityDmaintenanceAn MCP server for AI-powered image processing (generate, edit, vary, analyze) supporting OpenAI, Gemini, Ideogram, and custom relay endpoints.-
- AlicenseAqualityCmaintenanceMCP server for generating images and videos using Volcengine's Jimeng APIs, supporting text-to-image, image-to-image, multi-image fusion, text-to-video, and image-to-video.31MIT
- AlicenseAqualityDmaintenanceMCP server for AI image generation supporting text-to-image and image-to-image editing via any OpenAI-compatible service, with configurable models, aspect ratios, and sizes.2MIT