Wavespeed Mcp

What is Wavespeed Mcp about?

Enables client applications to invoke WaveSpeed AI’s advanced image and video generation services through a standardized MCP interface. It abstracts API interaction, polling, and resource management, allowing tools like Claude Desktop to call generation functions as native MCP tools.

How to use Wavespeed Mcp?

1. Install the package:

   pip install wavespeed-mcp
   

2. Provide your WaveSpeed API key via environment variable WAVESPEED_API_KEY or the --api-key argument.
3. Start the server:

   wavespeed-mcp --api-key your_api_key_here
   

4. (Optional) Generate a Claude Desktop configuration file:

   python -m wavespeed_mcp --api-key your_api_key_here --config-path /path/to/claude/config
   

5. Configure your IDE or client with the MCP server entry:

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

Key features of Wavespeed Mcp

• Advanced image generation: text‑to‑image, image‑to‑image, inpainting, LoRA support.
• Dynamic video generation from static images with customizable motion.
• Intelligent API polling with retry logic and progress tracking.
• Flexible output modes: URL, Base64, or local file storage.
• Comprehensive exception hierarchy for precise error handling.
• Detailed logging with configurable log levels.
• Multiple configuration sources: environment variables, CLI arguments, JSON config files.

Use cases of Wavespeed Mcp

• Integrating AI‑generated visuals into IDE extensions or desktop tools.
• Automating content creation pipelines for marketing, gaming, or social media.
• Providing on‑demand video assets for presentations or tutorials.
• Enabling AI‑assisted design tools that require real‑time image manipulation.

FAQ from the Wavespeed Mcp

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

Q: How do I choose the resource output mode? A: Set WAVESPEED_API_RESOURCE_MODE to url, base64, or local (default url).

Q: Can I customize API endpoints? A: Yes, via environment variables such as WAVESPEED_API_TEXT_TO_IMAGE_ENDPOINT.

Q: Where are generated files saved by default? A: To ~/Desktop unless overridden by WAVESPEED_MCP_BASE_PATH.

Q: How is logging controlled? A: Through WAVESPEED_LOG_LEVEL (DEBUG, INFO, WARNING, ERROR).

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.