Skip to main content
Glama
SeeDream MCP Server
by syh52

SeeDream MCP Server

npm version License: MIT

让 Claude Code 直接生成图片的 MCP 服务器,基于 BytePlus SeeDream 4.5 模型。

English | 中文


中文

✨ 功能

工具

说明

示例

seedream_generate

文本生成图片

"生成一张赛博朋克城市夜景"

seedream_edit

编辑现有图片

"给人物加上墨镜"

seedream_blend

多图融合

"把图1人物穿上图2衣服"

seedream_variations

批量生成变体

"生成4个不同配色方案"

seedream_status

检查服务状态

验证 API Key 和服务健康状态

⚡ v1.3.0 Web App 同步(最新)

  • Firebase 集成: 生成的图片自动同步到 Web App 共享图库

  • 无需登录: 所有人都能在 Web App 看到 MCP 生成的图片

  • Like 收藏: 用户登录后可以 like 收藏喜欢的图片

⚡ v1.2.0 流式生成

  • 流式 API: 图片生成一张返回一张,无需等待全部完成,体感速度大幅提升

  • 实时下载: 边生成边下载,图片到达即开始保存

⚡ v1.1.0 性能优化

  • 并行下载: 最多 4 张图片同时下载,批量生成速度提升 ~60%

  • 智能缓存: Base64 编码缓存,重复使用相同图片无需重新编码

  • 自动重试: 下载失败自动重试 2 次,带指数退避

  • 性能指标: 每次生成显示详细耗时(生成/下载/总计)

  • 结构化输出: 所有工具支持 outputSchema,便于程序化处理

  • HTTP 模式: 支持作为远程服务器部署(设置 TRANSPORT=http)

🚀 快速开始

1. 获取 API Key

访问 BytePlus ModelArk Console 获取 API Key。

2. 设置环境变量

# macOS/Linux
echo 'export ARK_API_KEY="your-api-key"' >> ~/.zshrc
source ~/.zshrc

# Windows (PowerShell)
[Environment]::SetEnvironmentVariable("ARK_API_KEY", "your-api-key", "User")

3. 配置 Claude Code

在你的项目根目录创建 .mcp.json:

{
  "mcpServers": {
    "seedream": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "seedream-mcp-server"],
      "env": {
        "ARK_API_KEY": "${ARK_API_KEY}"
      }
    }
  }
}

或者添加到全局配置 ~/.claude.json:

{
  "mcpServers": {
    "seedream": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "seedream-mcp-server"],
      "env": {
        "ARK_API_KEY": "${ARK_API_KEY}"
      }
    }
  }
}

4. 重启 Claude Code

重启后即可使用!

💬 使用示例

在 Claude Code 中直接说:

生成一张日本樱花树下的咖啡店,温暖的下午阳光,插画风格
把这张图片 ./photo.jpg 的背景换成星空
把 person.jpg 的人物穿上 dress.jpg 的裙子
基于这个 logo 生成6个不同配色方案

📁 输出

生成的图片会自动保存到 ./generated_images/ 目录。

输出示例(带性能指标):

# Image Generated Successfully

**Prompt:** 一只橘猫在阳光下打盹
**Size:** 2K

## Generated Images

### Image 1
- **URL:** https://...
- **Local:** `./generated_images/seedream_2024-01-27_12-30-45_1.jpg`
- **Size:** 2K

## Performance
- Generation: 15.2s
- Download: 1.8s
- **Total: 17.0s**

Related MCP server: gemini-image-mcp

English

✨ Features

Tool

Description

Example

seedream_generate

Text-to-image

"Generate a cyberpunk city at night"

seedream_edit

Edit existing image

"Add sunglasses to the person"

seedream_blend

Blend multiple images

"Dress person in image 1 with outfit from image 2"

seedream_variations

Batch variations

"Generate 4 color variations"

seedream_status

Check server status

Verify API key and server health

⚡ v1.3.0 Web App Sync (Latest)

  • Firebase Integration: Generated images automatically sync to Web App shared gallery

  • No Login Required: Everyone can see MCP-generated images in the Web App

  • Like & Save: Logged-in users can like and save their favorite images

⚡ v1.2.0 Streaming Generation

  • Streaming API: Images returned as they're generated, no waiting for all to complete

  • Real-time Downloads: Download starts immediately when each image is ready

⚡ v1.1.0 Performance Optimizations

  • Parallel Downloads: Up to 4 concurrent image downloads, ~60% faster for batch generation

  • Smart Caching: Base64 encoding cache for repeated image inputs

  • Auto Retry: Failed downloads retry up to 2 times with exponential backoff

  • Performance Metrics: Detailed timing for each generation (generation/download/total)

  • Structured Output: All tools support outputSchema for programmatic processing

  • HTTP Mode: Deploy as a remote server (set TRANSPORT=http)

🚀 Quick Start

1. Get API Key

Visit BytePlus ModelArk Console to get your API key.

2. Set Environment Variable

# macOS/Linux
echo 'export ARK_API_KEY="your-api-key"' >> ~/.zshrc
source ~/.zshrc

# Windows (PowerShell)
[Environment]::SetEnvironmentVariable("ARK_API_KEY", "your-api-key", "User")

3. Configure Claude Code

Create .mcp.json in your project root:

{
  "mcpServers": {
    "seedream": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "seedream-mcp-server"],
      "env": {
        "ARK_API_KEY": "${ARK_API_KEY}"
      }
    }
  }
}

Or add to global config ~/.claude.json:

{
  "mcpServers": {
    "seedream": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "seedream-mcp-server"],
      "env": {
        "ARK_API_KEY": "${ARK_API_KEY}"
      }
    }
  }
}

4. Restart Claude Code

Restart and you're ready to go!

💬 Usage Examples

Just talk to Claude Code:

Generate a serene Japanese garden with cherry blossoms, morning mist, photorealistic
Change the background of ./photo.jpg to a beach sunset
Dress the person in person.jpg with the outfit from dress.jpg
Generate 4 seasonal variations of this coffee shop interior

📁 Output

Generated images are automatically saved to ./generated_images/.


🔥 Firebase 同步配置 / Firebase Sync Setup

要让 MCP 生成的图片自动同步到 Web App,需要配置 Firebase Service Account:

To sync MCP-generated images to the Web App, configure Firebase Service Account:

1. 获取 Service Account / Get Service Account

  1. 访问 Firebase Console

  2. 点击 "Generate new private key" 下载 JSON 文件

  3. 将文件保存到安全位置

2. 配置环境变量 / Set Environment Variable

# 方法一:指定文件路径 / Method 1: File path
export FIREBASE_SERVICE_ACCOUNT_PATH="/path/to/service-account.json"

# 方法二:JSON 字符串(适合 CI/CD)/ Method 2: JSON string (for CI/CD)
export FIREBASE_SERVICE_ACCOUNT='{"type":"service_account",...}'

# 方法三:标准 GCP 方式 / Method 3: Standard GCP approach
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"

3. 更新 MCP 配置 / Update MCP Config

{
  "mcpServers": {
    "seedream": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "seedream-mcp-server"],
      "env": {
        "ARK_API_KEY": "${ARK_API_KEY}",
        "FIREBASE_SERVICE_ACCOUNT_PATH": "${FIREBASE_SERVICE_ACCOUNT_PATH}"
      }
    }
  }
}

配置完成后,MCP 生成的图片会自动出现在 SeeDream Gallery 中!

Once configured, MCP-generated images will automatically appear in SeeDream Gallery!


🌐 HTTP 服务器模式 / HTTP Server Mode

除了默认的 stdio 模式,还可以作为 HTTP 服务器运行:

In addition to the default stdio mode, you can run as an HTTP server:

# 启动 HTTP 服务器 / Start HTTP server
TRANSPORT=http PORT=3000 ARK_API_KEY=your-key node dist/index.js

# 或使用 npx / Or using npx
TRANSPORT=http PORT=3000 ARK_API_KEY=your-key npx seedream-mcp-server

端点 / Endpoints:

  • POST /mcp - MCP 协议端点

  • GET /health - 健康检查

  • GET / - 服务器信息


📝 License

MIT

Available Tools

6 tools
seedream_blendBlend Multiple ImagesA

Combine elements from multiple images using SeeDream 4.5.

⚠️ CLAUDE.AI USERS: This tool WILL TIMEOUT on Claude.ai (takes 30-60 seconds). Use "seedream_submit" instead with mode="multi" for Claude.ai compatibility.

Use this tool to blend 2-14 reference images together. Perfect for:

  • Virtual try-on: Dress person from image 1 in clothes from image 2

  • Face/Subject swap: Put face/subject from image 1 onto body/scene in image 2

  • Style transfer: Apply style of image 2 to content of image 1

  • Product visualization: Put product from image 1 into scene from image 2

  • Character consistency: Combine character traits from multiple references

Args:

  • prompt (string, required): Blending instruction referencing images by number

  • images (string[], required): Array of 2-14 image URLs or local paths

  • size (string): Output size (default: '2K')

  • strength (number): Reference strength 0-1 (default: 0.7)

  • watermark (boolean): Add watermark (default: false)

  • download (boolean): Save locally (default: true)

  • download_dir (string): Local save directory

Returns: Blended image URL, local path if downloaded, and performance timing.

Prompt Structure (per official docs):

  • Reference Target: Clearly specify what to extract from each reference image

  • Scene Description: Describe the output scene layout and composition

  • Always reference images by number: "image 1", "image 2", etc.

Common Use Cases:

  • Virtual try-on: "Dress the character in Image 1 with the outfit from Image 2"

  • Subject replacement: "Replace the subject in Image 1 with the subject from Image 2"

  • Style transfer: "Apply the style of Image 2 to Image 1"

  • Product placement: "Place the product from Image 1 on the table in Image 2"

Examples:

  • "Replace the clothing in image 1 with the outfit from image 2"

  • "Put the face from image 1 onto the body in image 2, maintaining natural lighting"

  • "Apply the linear minimalist style of image 2 to design icons based on image 1"

  • "Generate four tops in different materials, based on the clothing style worn by the girl in the reference images"

Tips:

  • Be specific about which elements to take from each image

  • For best results, use similar aspect ratios for inputs

  • Higher strength preserves more details from reference images

  • Using 10+ reference images significantly impacts generation speed

Inputs: images (required), prompt (required), size, download, +4 more. Returns: usage, images, prompt, timing, +4 more

seedream_editEdit ImageA

Edit an existing image based on text instructions using SeeDream 4.5.

⚠️ CLAUDE.AI USERS: This tool WILL TIMEOUT on Claude.ai (takes 20-40 seconds). Use "seedream_submit" instead with mode="image" for Claude.ai compatibility.

Use this tool to modify, enhance, or transform an existing image. Supports:

  • Addition: Add elements (accessories, objects, background elements)

  • Deletion: Remove unwanted elements

  • Replacement: Swap one element for another

  • Modification: Change colors, styles, lighting, expressions

  • Style transfer: Apply artistic styles to photos

Args:

  • prompt (string, required): Edit instruction describing the changes

  • image (string, required): Source image URL or local file path

  • size (string): Output size (default: '2K')

  • strength (number): Reference strength 0-1 (default: 0.7)

  • watermark (boolean): Add watermark (default: false)

  • download (boolean): Save locally (default: true)

  • download_dir (string): Local save directory

Returns: Edited image URL, local path if downloaded, and performance timing.

Edit Instruction Best Practices (per official docs):

  • Use concise, unambiguous instructions

  • Be specific: "the person's shirt" not "it"

  • Specify what should remain unchanged: "keeping the pose unchanged"

  • For targeted edits: draw arrows/boxes on image and reference them Example: "Insert a TV where the red area is marked"

Supported Operations:

  • Addition: "Add matching silver earrings and a necklace to the girl"

  • Deletion: "Remove the girl's hat"

  • Replacement: "Replace the largest bread man with a croissant man"

  • Modification: "Turn the robots into transparent crystal, colored red, yellow and green"

Examples:

  • "Add sunglasses to the person, keeping everything else unchanged"

  • "Change the background to a beach sunset"

  • "Apply Van Gogh oil painting style to this photo"

  • "Remove the text from the image"

  • "Dress the tallest panda in pink Peking Opera costume, keeping its pose unchanged"

Inputs: image (required), prompt (required), size, download, +4 more. Returns: usage, images, prompt, timing, +3 more

seedream_generateGenerate Image from TextA

Generate images from a text description using SeeDream 4.5.

⚠️ CLAUDE.AI USERS: This tool WILL TIMEOUT on Claude.ai (takes 30-60 seconds). Use "seedream_submit" instead with mode="text" for Claude.ai compatibility.

This is the primary tool for creating images from scratch. Default: Generates 4 images per prompt using streaming for fast response.

Args:

  • prompt (string, required): Detailed description of the image to generate

  • size (string): '2K' (default), '4K', '4K-9:16' (2304x4096 high-res vertical), or aspect ratios: '1:1', '4:3', '3:4', '16:9', '9:16', '3:2', '2:3', '21:9'

  • watermark (boolean): Add 'AI generated' watermark (default: false)

  • download (boolean): Save to local directory (default: true)

  • download_dir (string): Local save directory (default: ./generated_images)

  • response_format ('markdown' | 'json'): Output format

Returns: Generated image URL(s), local file path(s) if downloaded, and performance timing.

Prompt Best Practices (per official docs):

  • Structure: Subject + Action + Environment

  • For aesthetics add: Style, Color, Lighting, Composition

  • For text in images: use double quotes - 'poster with title "Hello World"'

  • Specify application context: "Design a logo for...", "Create a poster for..."

  • Keep under 600 English words; concise is better than verbose

Examples:

  • "A girl in a lavish dress walking under a parasol along a tree-lined path, in the style of a Monet oil painting"

  • "Design a logo for a gaming company. The logo features a dog playing with a game controller. The company name 'PITBULL' is written on it."

  • "Vibrant close-up editorial portrait, model with piercing gaze, wearing a sculptural hat, rich color blocking, Vogue magazine aesthetic"

  • "A cluttered office desk with an open laptop showing green code, a mug with the word 'Developer' on it, sunlight from the right"

Tips:

  • Be specific: "golden retriever puppy" > "dog"

  • Use natural language, not keyword lists

  • Include style keywords: "oil painting style", "anime art", "photorealistic"

  • Specify composition: "close-up portrait", "bird's eye view", "cinematic wide shot"

Inputs: prompt (required), size, download, watermark, +2 more. Returns: usage, images, prompt, timing, +1 more

seedream_statusCheck Server StatusA
Read-onlyIdempotent

Check the health and status of the SeeDream MCP server.

Use this tool to verify the server is working correctly before generating images. This does NOT consume API quota - it's a free diagnostic check.

Args:

  • verbose (boolean): Include detailed system info (default: false)

Returns: Server health status, configuration check, and available tools.

Use when:

  • First connecting to verify everything is set up correctly

  • Troubleshooting when image generation fails

  • Checking if API key is configured properly

Inputs: verbose. Returns: status, platform, memory_mb, node_version, +6 more

seedream_submitSubmit Image Generation TaskA

Submit an image generation task. Returns immediately - images will appear in the Web App.

USE THIS TOOL ON CLAUDE.AI - The regular seedream_generate tool times out on Claude.ai. This tool returns immediately after submitting the task.

After submitting: View your generated images at https://seedream-gallery.firebaseapp.com

Args:

  • prompt (string, required): Description of the image to generate

  • mode (string): 'text' (default), 'image' (editing with 1 ref image), or 'multi' (blending 2+ images)

  • size (string): '2K' (default), '4K', '4K-9:16' (2304x4096), or aspect ratios: '1:1', '4:3', '3:4', '16:9', '9:16', '3:2', '2:3', '21:9'

  • count (number): Number of images to generate (1-15, default: 4)

  • strength (number): Reference strength 0-1 for image/multi modes (default: 0.7)

  • images (string[]): Reference image URLs for 'image' or 'multi' modes

Examples:

  • Text mode: { prompt: "A sunset over mountains", mode: "text" }

  • Image mode: { prompt: "Make this photo look like an oil painting", mode: "image", images: ["https://...jpg"] }

Inputs: prompt (required), mode, size, count, +2 more. Returns: status, message, success, entry_id

seedream_variationsGenerate Image VariationsA

Generate multiple variations of an image concept using SeeDream 4.5.

⚠️ CLAUDE.AI USERS: This tool WILL TIMEOUT on Claude.ai (takes 30-90 seconds). Use "seedream_submit" instead for Claude.ai compatibility.

Use this tool to create 2-15 coherent variations based on a prompt. Great for:

  • A/B testing: Generate multiple options to compare

  • Storyboards: Create a series of related images

  • Product variations: Same product in different colors/styles

  • Exploration: See different interpretations of your concept

  • Social media: Multiple posts from one concept

Args:

  • prompt (string, required): Base concept for generating variations. Include batch keywords like "a series", "a set", "Generate X images" for best results.

  • count (number): Number of variations to generate (2-15, default: 4)

  • base_image (string, optional): Reference image to create variations from

  • size (string): Output size (default: '2K')

  • watermark (boolean): Add watermark (default: false)

  • download (boolean): Save locally (default: true)

  • download_dir (string): Local save directory

Returns: Array of variation image URLs, local paths if downloaded, and performance timing.

Prompt Best Practices (per official docs):

  • Include batch keywords: "a series of", "a set of", "Generate X images"

  • Describe variations explicitly: "4 seasonal versions", "different color schemes"

  • For storyboards: describe each panel's content in sequence

  • Keep prompts under 600 English words for best results

Examples:

  • "Generate a series of 4 seasonal variations of a cozy coffee shop interior"

  • "Create a set of 6 color variations of this minimalist logo design"

  • "Generate 4 different poses of this anime character in action"

  • "Create a 4-panel storyboard: morning coffee, commute, work, evening relaxation"

Tips:

  • The model maintains consistency across variations automatically

  • Use count=4 for quick comparisons, higher for more options

  • Adding a base_image helps maintain visual consistency

  • Note: base_image cannot be combined with batch generation (API limitation)

Inputs: prompt (required), size, count, download, +4 more. Returns: usage, images, prompt, timing, +4 more

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 6 tools

    Disambiguation3/5

    The core image tools are mostly distinguishable: generate creates from text, edit modifies a single image, blend combines multiple images, and variations makes coherent batches. However, seedream_submit duplicates generate/edit/blend behavior with only async execution as the differentiator, which creates real ambiguity about which tool an agent should select.

    Naming Consistency4/5

    All tools share the consistent seedream_ prefix and mostly use verb-style suffixes (edit, generate, blend, submit). variations and status are noun suffixes, which is a minor deviation, but the overall pattern remains predictable and readable.

    Tool Count4/5

    Six tools is a reasonable size for an image generation server, and most tools serve a distinct purpose. However, seedream_submit largely overlaps with the other image tools and exists primarily as a compatibility workaround, making the set feel slightly padded.

    Completeness4/5

    The server covers the main image workflows well: generation, editing, blending, variations, and health checking. The notable gap is that seedream_submit offers no MCP-based way to poll for results or retrieve submitted task outputs programmatically, forcing users to check an external web app.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers