# 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 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](https://wavespeed.ai))
### Setup
Install directly from PyPI:
```bash
pip install wavespeed-mcp
```
### MCP Configuration
To use WavespeedMCP with your IDE or application, add the following configuration:
```json
{
"mcpServers": {
"Wavespeed": {
"command": "wavespeed-mcp",
"env": {
"WAVESPEED_API_KEY": "wavespeedkey"
}
}
}
}
```
## Usage
### Running the Server
Start the WavespeedMCP server:
```bash
wavespeed-mcp --api-key your_api_key_here
```
### Claude Desktop Integration
WavespeedMCP can be integrated with Claude Desktop. To generate the necessary configuration file:
```bash
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:
```bash
pytest
```
Or with coverage reporting:
```bash
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.
Raw data
{
"_id": null,
"home_page": null,
"name": "wavespeed-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "wavespeed, mcp, image-generation, video-generation",
"author": null,
"author_email": "Wavespeed AI Team <support@wavespeed.ai>",
"download_url": "https://files.pythonhosted.org/packages/37/ef/fd65b8ac953b05a15354ecf147d7cd32f4e9650b25db9cd4272e0ffd67c2/wavespeed-mcp-0.1.15.tar.gz",
"platform": null,
"description": "# WavespeedMCP\n\n## [English](README.md) \uff5c [\u4e2d\u6587\u6587\u6863](README.zh.md)\n\nWavespeedMCP 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.\n\n## Features\n\n- **Advanced Image Generation**: Create high-quality images from text prompts with support for image-to-image generation, inpainting, and LoRA models\n- **Dynamic Video Generation**: Transform static images into videos with customizable motion parameters\n- **Optimized Performance**: Enhanced API polling with intelligent retry logic and detailed progress tracking\n- **Flexible Resource Handling**: Support for URL, Base64, and local file output modes\n- **Comprehensive Error Handling**: Specialized exception hierarchy for precise error identification and recovery\n- **Robust Logging**: Detailed logging system for monitoring and debugging\n- **Multiple Configuration Options**: Support for environment variables, command-line arguments, and configuration files\n\n## Installation\n\n### Prerequisites\n\n- Python 3.11+\n- WaveSpeed API key (obtain from [WaveSpeed AI](https://wavespeed.ai))\n\n### Setup\n\nInstall directly from PyPI:\n\n```bash\npip install wavespeed-mcp\n```\n\n### MCP Configuration\n\nTo use WavespeedMCP with your IDE or application, add the following configuration:\n\n```json\n{\n \"mcpServers\": {\n \"Wavespeed\": {\n \"command\": \"wavespeed-mcp\",\n \"env\": {\n \"WAVESPEED_API_KEY\": \"wavespeedkey\"\n }\n }\n }\n}\n```\n\n## Usage\n\n### Running the Server\n\nStart the WavespeedMCP server:\n\n```bash\nwavespeed-mcp --api-key your_api_key_here\n```\n\n### Claude Desktop Integration\n\nWavespeedMCP can be integrated with Claude Desktop. To generate the necessary configuration file:\n\n```bash\npython -m wavespeed_mcp --api-key your_api_key_here --config-path /path/to/claude/config\n```\n\nThis command generates a `claude_desktop_config.json` file that configures Claude Desktop to use WavespeedMCP tools. After generating the configuration:\n\n1. Start the WavespeedMCP server using the `wavespeed-mcp` command\n2. Launch Claude Desktop, which will use the configured WavespeedMCP tools\n\n## Configuration Options\n\nWavespeedMCP can be configured through:\n\n1. **Environment Variables**:\n\n - `WAVESPEED_API_KEY`: Your WaveSpeed API key (required)\n - `WAVESPEED_API_HOST`: API host URL (default: https://api.wavespeed.ai)\n - `WAVESPEED_MCP_BASE_PATH`: Base path for output files (default: ~/Desktop)\n - `WAVESPEED_API_RESOURCE_MODE`: Resource output mode (options: url, base64, local; default: url)\n - `WAVESPEED_LOG_LEVEL`: Logging level (options: DEBUG, INFO, WARNING, ERROR; default: INFO)\n - `WAVESPEED_API_TEXT_TO_IMAGE_ENDPOINT`: Custom endpoint for text-to-image generation (default: /wavespeed-ai/flux-dev)\n - `WAVESPEED_API_IMAGE_TO_IMAGE_ENDPOINT`: Custom endpoint for image-to-image generation (default: /wavespeed-ai/flux-kontext-pro)\n - `WAVESPEED_API_VIDEO_ENDPOINT`: Custom endpoint for video generation (default: /wavespeed-ai/wan-2.1/i2v-480p-lora)\n\n2. **Command-line Arguments**:\n\n - `--api-key`: Your WaveSpeed API key\n - `--api-host`: API host URL\n - `--config`: Path to configuration file\n\n3. **Configuration File** (JSON format):\n See `wavespeed_mcp_config_demo.json` for an example.\n\n## Architecture\n\nWavespeedMCP follows a clean, modular architecture:\n\n- `server.py`: Core MCP server implementation with tool definitions\n- `client.py`: Optimized API client with intelligent polling\n- `utils.py`: Comprehensive utility functions for resource handling\n- `exceptions.py`: Specialized exception hierarchy for error handling\n- `const.py`: Constants and default configuration values\n\n## Development\n\n### Requirements\n\n- Python 3.11+\n- Development dependencies: `pip install -e \".[dev]\"`\n\n### Testing\n\nRun the test suite:\n\n```bash\npytest\n```\n\nOr with coverage reporting:\n\n```bash\npytest --cov=wavespeed_mcp\n```\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Support\n\nFor support or feature requests, please contact the WaveSpeed AI team at support@wavespeed.ai.\n",
"bugtrack_url": null,
"license": null,
"summary": "WaveSpeed MCP Server",
"version": "0.1.15",
"project_urls": null,
"split_keywords": [
"wavespeed",
" mcp",
" image-generation",
" video-generation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7fb538450372049f4c13b1f1cc285207616e97a60a295c507a14df20c883ef10",
"md5": "5a7c38caefbceb5e12ecb081f7589fe5",
"sha256": "c3bfe36d85a974b94a1a4dc3e5947e325be906be1f7e65af1c8c985f09161b19"
},
"downloads": -1,
"filename": "wavespeed_mcp-0.1.15-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5a7c38caefbceb5e12ecb081f7589fe5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 16503,
"upload_time": "2025-09-09T06:50:31",
"upload_time_iso_8601": "2025-09-09T06:50:31.998457Z",
"url": "https://files.pythonhosted.org/packages/7f/b5/38450372049f4c13b1f1cc285207616e97a60a295c507a14df20c883ef10/wavespeed_mcp-0.1.15-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "37effd65b8ac953b05a15354ecf147d7cd32f4e9650b25db9cd4272e0ffd67c2",
"md5": "fc5211cd6fc8a4c0d4ebff275456b715",
"sha256": "a21c3dd6ce59ef9d06a2c687f315f6c52c4ed39bd0b6dfec1ea885edaaaa689b"
},
"downloads": -1,
"filename": "wavespeed-mcp-0.1.15.tar.gz",
"has_sig": false,
"md5_digest": "fc5211cd6fc8a4c0d4ebff275456b715",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 18302,
"upload_time": "2025-09-09T06:50:36",
"upload_time_iso_8601": "2025-09-09T06:50:36.278368Z",
"url": "https://files.pythonhosted.org/packages/37/ef/fd65b8ac953b05a15354ecf147d7cd32f4e9650b25db9cd4272e0ffd67c2/wavespeed-mcp-0.1.15.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-09 06:50:36",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "wavespeed-mcp"
}
JSON