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

    Related MCP Connectors

    Related MCP Servers