Wavespeed MCP

What is Wavespeed MCP about?

Wavespeed MCP offers a server implementation of the Model Control Protocol that bridges client applications with WaveSpeed AI's image‑to‑text, image‑to‑image, inpainting, and dynamic video generation services. It standardizes request/response handling, progress tracking, and error management, allowing developers to integrate high‑quality visual AI capabilities without dealing directly with the underlying REST endpoints.

How to use Wavespeed MCP?

1. Install – the package is published on PyPI:

   pip install wavespeed-mcp
   

2. Configure – supply the required API key and optional settings via one of three methods:
   • Environment variables (e.g., WAVESPEED_API_KEY, WAVESPEED_API_HOST, WAVESPEED_API_RESOURCE_MODE)
   • Command‑line arguments (--api-key, --api-host, --config)
   • JSON configuration file (see wavespeed_mcp_config_demo.json)
3. Run the server:

   wavespeed-mcp --api-key <YOUR_API_KEY>
   

4. Integrate – tools such as Claude Desktop can generate a companion configuration file:

   python -m wavespeed_mcp --api-key <YOUR_API_KEY> --config-path /path/to/claude/config
   

   Afterwards, start the server and launch the client application.

Key Features

• Advanced image generation: text‑to‑image, image‑to‑image, and LoRA‑based inpainting
• Dynamic video generation from static images with customizable motion parameters
• Intelligent API polling with retry logic and detailed progress updates
• Flexible output handling: URL, Base64, or local file storage
• Hierarchical exception classes for precise error identification
• Comprehensive logging with configurable log levels
• Multiple configuration sources (env, CLI, JSON file) for easy deployment

Use Cases

• Building AI‑powered creative assistants that produce images or short videos on demand
• Integrating visual generation into IDE extensions or desktop applications (e.g., Claude Desktop)
• Automating content creation pipelines for marketing assets, thumbnails, or storyboard visuals
• Prototyping multimedia features in SaaS products without managing low‑level API calls

FAQ

Q: Which Python version is required? A: Python 3.11 or newer.

Q: Do I need a WaveSpeed account? A: Yes, an API key from WaveSpeed AI is mandatory.

Q: Can I change the default API endpoints? A: Absolutely. Override them via environment variables such as WAVESPEED_API_TEXT_TO_IMAGE_ENDPOINT.

Q: How are resources returned? A: Choose between url, base64, or local modes using WAVESPEED_API_RESOURCE_MODE.

Q: Is there test coverage? A: A pytest suite is provided; run pytest or pytest --cov=wavespeed_mcp to verify functionality.

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.

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-mcp

MCP Configuration

To use WavespeedMCP with your IDE or application, add the following configuration:

{
  "mcpServers": {
    "Wavespeed": {
      "command": "wavespeed-mcp",
      "env": {
        "WAVESPEED_API_KEY": "wavespeedkey"
      }
    }
  }
}

Usage

Running the Server

Start the WavespeedMCP server:

wavespeed-mcp --api-key your_api_key_here

Claude 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/config

This command generates a claude_desktop_config.json file that configures Claude Desktop to use WavespeedMCP tools. After generating the configuration:

1. Start the WavespeedMCP server using the wavespeed-mcp command
2. Launch Claude Desktop, which will use the configured WavespeedMCP tools

Configuration Options

WavespeedMCP can be configured through:

1. 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)

2. Command-line Arguments:

   • --api-key: Your WaveSpeed API key
   • --api-host: API host URL
   • --config: Path to configuration file

3. Configuration File (JSON format): See wavespeed_mcp_config_demo.json for an example.

Architecture

WavespeedMCP follows a clean, modular architecture:

• server.py: Core MCP server implementation with tool definitions
• client.py: Optimized API client with intelligent polling
• utils.py: Comprehensive utility functions for resource handling
• exceptions.py: Specialized exception hierarchy for error handling
• const.py: Constants and default configuration values

Development

Requirements

• Python 3.11+
• Development dependencies: pip install -e ".[dev]"

Testing

Run the test suite:

pytest

Or with coverage reporting:

pytest --cov=wavespeed_mcp

License

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.