mcp-server-doubao

# Doubao MCP Server > Doubao AI model server based on Model Context Protocol (MCP), supporting image and video generation. [](https://www.npmjs.com/package/@tonychaos/mcp-server-doubao) [](https://opensource.org/licenses/MIT) ## ✨ Features ### 🎨 Image Generation (Doubao Seedream) #### Supported Models | Model | Task Type | Characteristics | |------|---------|------| | **doubao-seedream-5.0** | Text-to-Image, Single Image Generation, Multi-Image Fusion (2-14), Collage | 🔥 Latest, deep reasoning, web search, multi-turn interactive editing | | **doubao-seedream-4.5** | Text-to-Image, Single Image Generation, Multi-Image Fusion (2-14), Collage | 4K ultra-high definition, streaming output | | **doubao-seedream-4.0** | Text-to-Image, Single Image Generation, Multi-Image Fusion (2-14), Collage | 4K ultra-high definition, strong subject consistency | | **doubao-seedream-3.0-t2i** | Text-to-Image | Supports seed and guidance_scale | | **doubao-seededit-3.0-i2i** | Single Image Generation | Supports adaptive size | > 💡 **Note**: The server supports any valid Doubao model ID, including future releases. Just specify the `model` parameter when requesting. #### Core Capabilities - ✅ **Text-to-Image** - Generate images from pure text prompts - ✅ **Single Image Generation** - One reference image + text prompt → generate new image - ✅ **Multi-Image Fusion** - Multiple reference images (2-14) + text prompt → fusion generation - ✅ **Collage Function** - Generate a group of content-related images (up to 15) - ✅ **4K Ultra-High Definition** - Up to 4096x4096 resolution - ✅ **Custom Size** - Supports custom pixel values, such as 2560x1440 (16:9) - ✅ **Base64 Return** - Supports returning Base64-encoded image data - ✅ **Image Download** - Supports downloading images to a local specified path - ✅ **Prompt Optimization** - Automatically optimizes prompts to improve generation quality - ✅ **Watermark Control** - Optional watermark addition - ✅ **Streaming Output** - Real-time returns generation progress (4.5/4.0/5.0) - 🔥 **Web Search** - Get real-time information to generate content (5.0) - 🔥 **Deep Reasoning** - More intelligent understanding and generation capabilities (5.0) #### Image Requirements - **Format**: jpeg, png, webp, bmp, tiff, gif - **Size**: Maximum 10MB - **Resolution**: Total pixels ≤ 36,000,000 (6000x6000) - **Aspect Ratio**: [1/16, 16] (4.5/4.0), [1/3, 3] (3.0) ### 🎬 Video Generation (Doubao Seedance) #### Supported Task Types - ✅ **Text-to-Video** - Generate video from text prompts - ✅ **Image-to-Video** - Generate video from initial frame image and text - ✅ **Frames-to-Video** - Generate video from initial and final frame images and text - ✅ **Image-to-Video (with Mask)** - Generate video from image, mask, and text #### Core Capabilities - ✅ **Audio-Video Synchronization** - Automatically generate audio matching the video - ✅ **Asynchronous Processing** - Supports task creation and status query - ✅ **Task List** - Batch query task status - ✅ **Task Cancellation** - Cancel ongoing tasks - ✅ **Multiple Resolutions** - 720p, 1080p, 1440p ## 📦 Installation ### npm Global Installation ```bash npm install -g @tonychaos/mcp-server-doubao ``` ### npx Direct Run (no installation required) ```bash npx @tonychaos/mcp-server-doubao ``` ## ⚙️ Configuration ### 1. Get API Key 1. Visit [Volc Engine Console](https://console.volcengine.com/ark/region:ark+cn-beijing/overview) 2. Log in 3. Go to "API Key Management" to create an API Key ### 2. Configure Claude Desktop Add the following configuration to Claude Desktop's configuration file: **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "doubao": { "command": "npx", "args": ["-y", "@tonychaos/mcp-server-doubao"], "env": { "ARK_API_KEY": "your_api_key_here" } } } } ``` ### 3. Restart Claude Desktop After configuration, restart Claude Desktop to load the MCP server. ## 🚀 Usage ### Image Generation Example #### Text-to-Image (2K HD) ``` Use Doubao to generate a 2K image: An orange cat playing in a garden on a sunny day ``` #### Text-to-Image (4K Ultra-HD) ``` Use Doubao to generate a 4K image: A futuristic cityscape at night, cyberpunk style, with neon lights ``` #### Text-to-Image (Custom Aspect Ratio) ``` Use Doubao to generate a 21:9 image: A majestic landscape, panoramic view ``` #### Collage Generation ``` Use Doubao to generate a group of images (4): Forest landscapes of the four seasons ``` #### Single Image Generation ``` Use Doubao to generate a new image based on this image: https://example.com/cat.jpg Let the cat in the image wear a red hat, keeping other elements unchanged ``` #### Multi-Image Fusion ``` Use Doubao to generate a new image based on these two images: Image 1: https://example.com/style.jpg Image 2: https://example.com/content.jpg Apply the artistic style of Image 1 to the content of Image 2 ``` #### Watermark-Free High-Definition Image ``` Generate a watermark-free image: A golden retriever running on the beach ``` #### Image Download ``` Download this image and save it to ./downloads/cat.jpg: https://example.com/cat.jpg ``` ### Video Generation Example #### Text-to-Video ``` Use Doubao to generate a video: A drone flying at extremely high speed through complex obstacles, providing an immersive flying experience ``` #### Image-to-Video ``` Use Doubao to generate a video based on this image: https://example.com/frame.jpg Let the landscape in the image gradually become brighter, with the sun shining out from the clouds ``` #### Frames-to-Video ``` Use Doubao to generate a video based on these two images: Initial frame: https://example.com/start.jpg Final frame: https://example.com/end.jpg Description: Smooth day-to-night transition effect ``` #### Query Video Task Status ``` Query the status of video task task_id_xxx ``` #### Query All Video Tasks ``` Query all recently created video tasks ``` ## 🔧 Development ### Environment Requirements - Node.js >= 18.0.0 - npm or yarn ### Build Project ```bash # Install dependencies npm install # Build project npm run build # Run locally ARK_API_KEY=your_api_key_here npm start ``` ### Development Mode ```bash # Monitor file changes and rebuild automatically npm run watch # Build and run npm run dev ``` ### Run Tests ```bash # Image generation test npx tsx test-image.ts # Complete functional test npx tsx test-image-complete.ts # Video generation test npx tsx test-video.ts ``` ## 📚 API Reference ### Image Generation API **Endpoint**: `https://ark.cn-beijing.volces.com/api/v3/images/generations` **Supported Models**: - `doubao-seedream-5-0-260128` (Recommended, latest) - `doubao-seedream-4-5-251128` (4K ultra-high definition, streaming output) - `doubao-seedream-4-0-250428` (4K ultra-high definition) - `doubao-seedream-3-0-t2i` (Text-to-Image) - `doubao-seededit-3-0-i2i` (Image-to-Image) > 💡 **Hint**: The server supports any valid model ID, and future releases can be used without code updates. **Price Reference**: - 2K images: ~0.25 CNY/image - 4K images: ~0.5 CNY/image **Official Documentation**: [Image Generation API](https://www.volcengine.com/docs/82379/1541523) ### Video Generation API **Create Task**: `POST https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks` **Query Task**: `GET https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks/{id}` **Supported Models**: - `doubao-seedance-1-5-pro-251215` (Recommended) - `doubao-seedance-1-5` (Economy) **Price Reference**: - 1.5-pro (with audio): ~16 CNY/million tokens - 1.5 (with audio): ~4 CNY/million tokens **Official Documentation**: [Video Generation API](https://www.volcengine.com/docs/82379/1520757) ## 📁 Project Structure ``` mcp-server-doubao/ ├── src/ │ ├── index.ts # Main entry file │ ├── server.ts # MCP server configuration │ ├── tools/ # MCP tool implementation │ │ ├── image-generation.ts # Image generation tool │ │ └── video-generation.ts # Video generation tool │ ├── api/ # API client │ │ ├── client.ts # Basic API client │ │ ├── image-api.ts # Image generation API │ │ └── video-api.ts # Video generation API │ ├── types/ # TypeScript type definitions │ │ ├── index.ts │ │ ├── image.ts # Image-related types │ │ └── video.ts # Video-related types │ └── utils/ # Utility functions ├── dist/ # Compilation output directory ├── test-*.ts # Test files ├── package.json ├── tsconfig.json └── README.md ``` ## 🎯 Tool and Parameter Description ### Image Generation Tool #### generate_image (Text-to-Image/Collage) **Main Parameters**: - `prompt` (required): Text prompt - `model`: Model selection, default "doubao-seedream-5-0-260128" - `size`: Image size ("2K", "4K", "WIDTHxHEIGHT", "adaptive") - `sequential_image_generation`: Collage mode ("auto", "disabled") - `max_images`: Maximum number of generated images [1-15] - `response_format`: Return format ("url", "b64_json") - `watermark`: Optional watermark addition (default true) #### image_to_image (Image-to-Image/Multi-Image Fusion) **Main Parameters**: - `prompt` (required): Text prompt - `imageUrl`: Single reference image URL - `imageUrls`: Multiple reference image URL array [2-14] - `model`: Model selection - `size`: Image size - `sequential_image_generation`: Collage mode #### download_image (Image Download) **Main Parameters**: - `url` (required): Image URL (usually returned by generate_image) - `filePath` (required): Local save path (e.g., /path/to/image.png or ./downloads/image.jpg) **Function Description**: - Automatically carries authentication headers for download - Automatically creates the target directory (if it doesn't exist) - Returns the absolute path, file size, and content type ### Video Generation Tool #### generate_video (Create Video Task) **Main Parameters**: - `prompt` (required): Text prompt - `task_type`: Task type ("text_to_video", "image_to_video", "frames_to_video") - `image_url`: Initial frame image URL - `end_image_url`: Final frame image URL - `mask_url`: Mask image URL - `resolution`: Resolution ("720p", "1080p", "1440p") - `duration`: Video duration [3-10 seconds] #### query_video_task (Query Video Task) **Main Parameters**: - `task_id` (required): Task ID ## 📝 Changelog ### v1.3.0 (2026-03-15) - ✨ Supports Seedream 5.0 model - Added `doubao-seedream-5-0-260128` model support - Supports deep reasoning and web search functionality - Default uses the latest 5.0 model - 🎯 Open model selection mechanism - Supports any valid Doubao model ID - Future releases can be used without code updates - Known models listed in tool descriptions for reference - 📝 Updated documentation - Updated model list and feature descriptions - Added model usage suggestions ### v1.2.0 (2026-01-17) - ✨ Added image download functionality - Supports downloading images to a local specified path - Automatically carries authentication headers - Automatically creates the target directory - Returns save path, file size, and content type - 🐛 Fixed MCP tool parameter description display issue - Converted Zod schema to JSON Schema - Ensured MCP client correctly parses tool parameter information ### v1.1.0 (2025-01-11) - ✨ Added complete image generation functionality support - Supports 4 models (4.5, 4.0, 3.0-t2i, 3.0-i2i) - Text-to-Image, Single Image Generation, Multi-Image Fusion (2-14 images) - Collage functionality, generates up to 15 related images - 4K ultra-high definition output - Custom pixel value size - Base64 return format - Prompt optimization - Watermark control - Streaming output support - ✨ Added complete video generation functionality support - Supports 2 models (1.5-pro, 1.5) - 4 task types - Task status query - Task list query - Task cancellation functionality - 📝 Complete tool parameter descriptions and usage examples - 🧪 Added complete test cases ### v1.0.0 (2025-01-10) - 🎉 Initial version release - ✅ Basic image generation functionality - ✅ Basic video generation functionality ## 📄 License [MIT](LICENSE) ## 🔗 Related Links - [Doubao AI Official Website](https://www.doubao.com) - [Volc Engine Documentation](https://www.volcengine.com/docs/ark) - [Model Context Protocol](https://modelcontextprotocol.io) - [MCP SDK Documentation](https://github.com/modelcontextprotocol/typescript-sdk) ## 💬 Support If you have questions or suggestions, please submit an [Issue](https://github.com/oychao1988/mcp-server-doubao/issues). ## 🙏 Acknowledgments Thanks to [Anthropic](https://www.anthropic.com) for developing the Model Context Protocol framework.