WavespeedMCP

by WaveSpeedAI

30 stars

568 downloads

Not rated

GitHub

Other

Description

# WavespeedMCP ## [English](README.md) ｜ [中文文档](README.zh.md) 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…

About

Details

Author: WaveSpeedAI
GitHub stars: 30
Downloads: 568
Categories: Other

- Advanced image generation with text-to-image, image-to-image, inpainting, and LoRA support
- Dynamic video generation from static images with customizable motion parameters
- Optimized API polling with intelligent retry and progress tracking
- Flexible resource output modes: URL, Base64, and local files
- Comprehensive error handling with specialized exception hierarchy
- Robust logging with rotating file handler and configurable levels

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name WavespeedMCP

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "wavespeedmcp": {
            "mcp-server-wavespeedai": {
                "command": "python",
                "args": [
                    "-m",
                    "wavespeed_mcp",
                    "--api-key",
                    "your_api_key_here",
                    "--config-path",
                    "/path/to/claude/config"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "wavespeedmcp": {
            "mcp-server-wavespeedai": {
                "command": "python",
                "args": [
                    "-m",
                    "wavespeed_mcp",
                    "--api-key",
                    "your_api_key_here",
                    "--config-path",
                    "/path/to/claude/config"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "wavespeedmcp": {
            "mcp-server-wavespeedai": {
                "command": "python",
                "args": [
                    "-m",
                    "wavespeed_mcp",
                    "--api-key",
                    "your_api_key_here",
                    "--config-path",
                    "/path/to/claude/config"
                ]
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "wavespeedmcp": {
            "mcp-server-wavespeedai": {
                "command": "python",
                "args": [
                    "-m",
                    "wavespeed_mcp",
                    "--api-key",
                    "your_api_key_here",
                    "--config-path",
                    "/path/to/claude/config"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "wavespeedmcp": {
            "mcp-server-wavespeedai": {
                "command": "python",
                "args": [
                    "-m",
                    "wavespeed_mcp",
                    "--api-key",
                    "your_api_key_here",
                    "--config-path",
                    "/path/to/claude/config"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "wavespeedmcp": {
            "mcp-server-wavespeedai": {
                "command": "python",
                "args": [
                    "-m",
                    "wavespeed_mcp",
                    "--api-key",
                    "your_api_key_here",
                    "--config-path",
                    "/path/to/claude/config"
                ]
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "wavespeedmcp": {
            "mcp-server-wavespeedai": {
                "command": "python",
                "args": [
                    "-m",
                    "wavespeed_mcp",
                    "--api-key",
                    "your_api_key_here",
                    "--config-path",
                    "/path/to/claude/config"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "wavespeedmcp": {
            "mcp-server-wavespeedai": {
                "command": "python",
                "args": [
                    "-m",
                    "wavespeed_mcp",
                    "--api-key",
                    "your_api_key_here",
                    "--config-path",
                    "/path/to/claude/config"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "wavespeedmcp": {
            "mcp-server-wavespeedai": {
                "command": "python",
                "args": [
                    "-m",
                    "wavespeed_mcp",
                    "--api-key",
                    "your_api_key_here",
                    "--config-path",
                    "/path/to/claude/config"
                ]
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "wavespeedmcp": {
            "mcp-server-wavespeedai": {
                "command": "python",
                "args": [
                    "-m",
                    "wavespeed_mcp",
                    "--api-key",
                    "your_api_key_here",
                    "--config-path",
                    "/path/to/claude/config"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "wavespeedmcp": {
            "mcp-server-wavespeedai": {
                "command": "python",
                "args": [
                    "-m",
                    "wavespeed_mcp",
                    "--api-key",
                    "your_api_key_here",
                    "--config-path",
                    "/path/to/claude/config"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "wavespeedmcp": {
            "mcp-server-wavespeedai": {
                "command": "python",
                "args": [
                    "-m",
                    "wavespeed_mcp",
                    "--api-key",
                    "your_api_key_here",
                    "--config-path",
                    "/path/to/claude/config"
                ]
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "wavespeedmcp": {
            "mcp-server-wavespeedai": {
                "command": "python",
                "args": [
                    "-m",
                    "wavespeed_mcp",
                    "--api-key",
                    "your_api_key_here",
                    "--config-path",
                    "/path/to/claude/config"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "wavespeedmcp": {
            "mcp-server-wavespeedai": {
                "command": "python",
                "args": [
                    "-m",
                    "wavespeed_mcp",
                    "--api-key",
                    "your_api_key_here",
                    "--config-path",
                    "/path/to/claude/config"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "wavespeedmcp": {
            "mcp-server-wavespeedai": {
                "command": "python",
                "args": [
                    "-m",
                    "wavespeed_mcp",
                    "--api-key",
                    "your_api_key_here",
                    "--config-path",
                    "/path/to/claude/config"
                ]
            }
        }
    }
}

From the repository

Install via pip install wavespeed-mcp, set the WAVESPEED_API_KEY environment variable, and start the server with wavespeed-mcp --api-key your_api_key_here. Integrate with Claude Desktop by generating a configuration file using python -m wavespeed_mcp --api-key your_api_key_here --config-path /path/to/claude/config.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "wavespeedmcp": {
            "mcp-server-wavespeedai": {
                "command": "python",
                "args": [
                    "-m",
                    "wavespeed_mcp",
                    "--api-key",
                    "your_api_key_here",
                    "--config-path",
                    "/path/to/claude/config"
                ]
            }
        }
    }
}

McpServers

{
    "mcp-server-wavespeedai": {
        "command": "python",
        "args": [
            "-m",
            "wavespeed_mcp",
            "--api-key",
            "your_api_key_here",
            "--config-path",
            "/path/to/claude/config"
        ]
    }
}

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

```bash

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

Description

About

Details

Jump to

Setting up with Highlight

From the repository

Claude Desktop / Cursor

McpServers

WavespeedMCP

English ｜ 中文文档

Features

Installation

Prerequisites

Setup

MCP Configuration

Usage

Running the Server

Claude Desktop Integration

Configuration Options

Timeouts

Logging Configuration

Install

More like this

Sequential Thinking

Filesystem

EverArt

Google Drive

Reactive Resume

FastMCP v2 🚀

English ｜中文文档