Skip to main content
Glama

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

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": "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_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 saving generated files (default: ~/Desktop)

    • WAVESPEED_API_RESOURCE_MODE: Resource output mode - url, local, or base64 (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.log

The 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

  1. Command-line Arguments:

    • --api-key: Your WaveSpeed API key

    • --api-host: API host URL

    • --config: Path to configuration file

  2. 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.

Available Tools

3 tools
generate_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

    A4.2/5.0

    Scored across 3 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness2/5

    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

    Related MCP Servers