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.
- 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
- Python 3.11+
- WaveSpeed API key (obtain from WaveSpeed AI)
Install directly from PyPI:
pip install wavespeed-mcp
To use WavespeedMCP with your IDE or application, add the following configuration:
{
"mcpServers": {
"Wavespeed": {
"command": "wavespeed-mcp",
"env": {
"WAVESPEED_API_KEY": "wavespeedkey"
}
}
}
}
Start the WavespeedMCP server:
wavespeed-mcp --api-key your_api_key_here
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/config
This 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-mcp
command - Launch Claude Desktop, which will use the configured WavespeedMCP tools
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 output files (default: ~/Desktop)WAVESPEED_API_RESOURCE_MODE
: Resource output mode (options: url, base64, local; default: url)WAVESPEED_LOG_LEVEL
: Logging level (options: DEBUG, INFO, WARNING, ERROR; default: INFO)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)
-
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.json
for an example.
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
- Python 3.11+
- Development dependencies:
pip install -e ".[dev]"
Run the test suite:
pytest
Or with coverage reporting:
pytest --cov=wavespeed_mcp
This project is licensed under the MIT License - see the LICENSE file for details.
For support or feature requests, please contact the WaveSpeed AI team at support@wavespeed.ai.