How do I use WavespeedMCP?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@WavespeedMCP Generate an image of a futuristic cityscape at night" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

WavespeedMCP

by honeyvig

Overview Schema Source Related Servers Discussions Admin

Python

Remote

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

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": "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:

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

Configuration Options

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

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.

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.

ParametersJSON Schema

Name	Required	Default
`image`	Yes
`prompt`	Yes
`model`	No
`negative_prompt`	No
`loras`	No
`size`	No	832*480
`num_inference_steps`	No
`duration`	No
`guidance_scale`	No
`flow_shift`	No
`seed`	No
`enable_safety_checker`	No
`output_directory`	No
`request_id`	No

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description fully discloses behavioral traits: it describes the generation process, parameter effects (e.g., guidance_scale controls text adherence, num_inference_steps affects quality/time), return values (status, urls, base64, local_files, error, processing_time), and even notes on language handling. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately structured with sections for Args, Returns, Examples, and Notes. Every sentence is informative; no filler. Despite length, it is clear and front-loaded with essential info (language requirement).

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 14 parameters and no output schema, the description covers all parameters, return types, and examples. It also provides critical notes (English-only, safety checker). No gaps remain given the complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage (only titles), but the description compensates by explaining each parameter's purpose, format, and defaults (e.g., loras format, size format, duration constraints). This adds significant value beyond the raw schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool generates a video using WaveSpeed AI, specifying required inputs (image and prompt). The verb 'generate' and resource 'video' are precise, and the name 'generate_video' aligns. Siblings are different (image-to-image, text-to-image), so purpose is well-distinguished.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage guidance: prompts must be English, duration must be 5 or 10, and includes examples. However, it does not explicitly compare with sibling tools or state when not to use this tool (e.g., for text-only video generation without an image).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`image`	Yes
`images`	Yes
`prompt`	Yes
`model`	No
`guidance_scale`	No
`enable_safety_checker`	No
`output_directory`	No
`request_id`	No

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description bears full responsibility. It discloses behavioral traits: uses WaveSpeed AI, requires English prompts, provides safety checker, and explains request_id for tracing. It also describes the return structure. However, it omits potential rate limits, authentication requirements, or error handling details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with a clear one-sentence summary followed by structured Args/Returns/Examples/Note sections. However, it is somewhat verbose with multiple examples and a note that could be shorter. Still, the structure aids readability and comprehension.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 8 parameters (3 required), no output schema, and no nested objects, the description is complete. It explains the return structure (status, urls, base64, local_files, error, processing_time) and provides examples showing different usage patterns. No additional context seems necessary for correct tool invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, meaning the input schema only provides names and types. The description adds substantial meaning: explains that 'image' and 'images' accept URL, base64, or local paths; describes prompt language requirement; specifies range and default for guidance_scale; explains safety checker, output directory, and request_id purpose. This is far beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool generates an image from an existing image using WaveSpeed AI. It effectively distinguishes from sibling tools: generate_video (video output) and text_to_image (no input image). The verb 'generate' and resource 'image from an existing image' are specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides examples and notes about English prompts, but lacks explicit guidance on when to use this tool versus alternatives like text_to_image or generate_video. The usage context is implied through examples but no exclusions or when-not scenarios are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Default
`prompt`	Yes
`model`	No
`loras`	No
`size`	No	1024*1024
`num_inference_steps`	No
`guidance_scale`	No
`num_images`	No
`seed`	No
`enable_safety_checker`	No
`output_directory`	No
`request_id`	No

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses behavior: it generates images, includes a safety checker, specifies default values for steps and size, and outlines the return object (status, URLs, base64, local files, processing time). No contradictions or hidden behaviors.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with Args, Returns, Examples, and Note sections. It is front-loaded with the purpose. Some detail is lengthy but necessary given the 0% schema coverage. Minor redundancy exists (e.g., English requirement repeated), but overall it earns its space.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite no output schema, the description fully specifies the return structure and includes examples. It covers all 11 parameters with defaults and constraints. The tool's complexity is high, but the description is complete and self-contained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema coverage is 0%, so the description must explain each parameter. It does so thoroughly: prompt is required and must be English, loras has a specific format, size is 'width*height', num_inference_steps affects quality/time, guidance_scale controls text adherence, etc. This adds significant meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a clear verb-resource pair: 'Generate an image from text prompt using WaveSpeed AI.' It explicitly states the action and resource, and the resource type (text-to-image) distinguishes it from sibling tools like generate_video and image_to_image.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage guidelines, such as requiring prompts in English and noting that non-English prompts will be rejected or produce poor quality. It also includes default values and parameter descriptions. However, it does not explicitly state when to use this tool over siblings, though the purpose implies it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

3 tool updatesv0.1.27Jun 21, 2026
- First observedgenerate_video
- First observedimage_to_image
- First observedtext_to_image

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.2/5.0

Scored 2026-06-21 08:55 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.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

mcp-wanOAuth
io.github.AceDataCloud
MCP server for Wan AI video generation
AI & Machine Learning Image & Video Processing
21
mcp-qwen-imageOAuth
io.github.AceDataCloud
MCP server for Qwen Image 3 AI image generation
AI & Machine Learning Image & Video Processing
1
mcp-veoOAuth
io.github.AceDataCloud
MCP server for Google Veo AI video generation
Multimedia Processing Image & Video Processing Entertainment & Media
23
mcp-hailuoOAuth
io.github.AceDataCloud
MCP server for Hailuo (MiniMax) AI video generation
AI & Machine Learning Image & Video Processing
21

Related MCP Servers

WaveSpeed MCP Serverofficial
AI & Machine Learning Image & Video Processing
WaveSpeedAI
A
license
A
quality
B
maintenance
Provides a standardized interface for accessing WaveSpeed's image and video generation capabilities through the MCP protocol.
Updated 13 days ago (2026-09-03 00:42 UTC)
7
131 npm
31
MIT
image-forge-mcp
Image & Video Processing AI & Machine Learning
Cheng77c
F
license
Not graded
quality
D
maintenance
An MCP server for AI-powered image processing (generate, edit, vary, analyze) supporting OpenAI, Gemini, Ideogram, and custom relay endpoints.
Updated 6 months ago (2026-03-03 09:42 UTC)
-
jimeng_visual_generation
Image & Video Processing AI & Machine Learning
justForever17
A
license
A
quality
C
maintenance
MCP server for generating images and videos using Volcengine's Jimeng APIs, supporting text-to-image, image-to-image, multi-image fusion, text-to-video, and image-to-video.
Updated 14 days ago (2026-09-01 07:21 UTC)
3
1
MIT
nanobanana-mcp
AI & Machine Learning Image & Video Processing
superboolgithub
F
license
A
quality
D
maintenance
MCP server for AI image generation supporting text-to-image and image-to-image editing via any OpenAI-compatible service, with configurable models, aspect ratios, and sizes.
Updated 7 months ago (2026-02-01 14:44 UTC)
2
-

WavespeedMCP

English ｜ 中文文档

Features

Installation

Prerequisites

Setup

MCP Configuration

Usage

Running the Server

Claude Desktop Integration

Configuration Options

Timeouts

Logging Configuration

Architecture

Development

Requirements

Testing

License

Support

Available Tools

TDQS

TDQS

TDQS

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

WaveSpeed MCP Serverofficial

image-forge-mcp

jimeng_visual_generation

nanobanana-mcp

English ｜中文文档