Overview
What is WavespeedMCP?
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.
How to use WavespeedMCP?
Install via pip install wavespeed-mcp, set the WAVESPEED_API_KEY environment variable, and start the server with wavespeed-mcp --api-key your_api_key_here. Integrate with Claude Desktop by generating a configuration file using python -m wavespeed_mcp --api-key your_api_key_here --config-path /path/to/claude/config.
Key features of WavespeedMCP
- Advanced image generation with text-to-image, image-to-image, inpainting, and LoRA support
- Dynamic video generation from static images with customizable motion parameters
- Optimized API polling with intelligent retry and progress tracking
- Flexible resource output modes: URL, Base64, and local files
- Comprehensive error handling with specialized exception hierarchy
- Robust logging with rotating file handler and configurable levels
Use cases of WavespeedMCP
- Generate high-quality images from text prompts for creative projects
- Transform static images into videos with adjustable motion settings
- Enhance existing images using inpainting or image-to-image workflows
- Automate media generation in applications via MCP (e.g., Claude Desktop)
FAQ from WavespeedMCP
What does WavespeedMCP provide beyond the raw WaveSpeed API?
WavespeedMCP wraps the WaveSpeed API into the MCP standard, adding intelligent polling, progress tracking, retry logic, and multiple output modes (URL, Base64, local). It also integrates seamlessly with MCP-compatible clients like Claude Desktop.
What are the runtime requirements for WavespeedMCP?
Python 3.11 or higher is required. You must also have a valid WaveSpeed API key, obtainable from the WaveSpeed AI website.
How are generated files stored and output?
Output mode is controlled by the WAVESPEED_API_RESOURCE_MODE environment variable (default: url). You can choose url, local, or base64. For local mode, files are saved under the path set by WAVESPEED_MCP_BASE_PATH (default: ~/Desktop).
How do I configure timeouts for API requests and polling?
Set WAVESPEED_REQUEST_TIMEOUT (per HTTP request, default 300s) and WAVESPEED_WAIT_RESULT_TIMEOUT (total polling time, default 600s) as environment variables. These control how long the server waits for individual calls and the overall job result.
What logging options are available?
By default logs go to console. To enable file logging, set the WAVESPEED_LOG_FILE environment variable to a path. The log file uses a rotating handler (max 10 MB, 5 backups) with format %(asctime)s - wavespeed-mcp - %(levelname)s - %(message)s. Log level is configurable via WAVESPEED_LOG_LEVEL.
