Skip to main content
Glama
fucheng830

volcengine-imagegen-mcp

by fucheng830
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

🎨 VolcEngine Image Generation MCP Server

License: MIT npm version MCP

纯 Node.js + TypeScript 实现的 MCP 服务器，为 Claude Desktop、VS Code、Cursor、Trae 等 AI 应用提供火山引擎豆包生图能力。

✨ 特性

  • 🎨 文生图: 根据文本提示词生成图片

  • 🖼️ 图生图: 根据参考图片和文本生成新图片

  • 📸 组图生成: 生成一组内容关联的图片（最多15张）

  • 🎯 多模型支持: 支持 doubao-seedream 4.5/4.0/3.0 系列

  • 📐 多尺寸支持: 2K, 4K, 1024x1024, 2048x2048

  • 🔄 灵活输出: 支持返回 URL 或 Base64 格式

  • 💧 水印控制: 可选择是否添加水印

Related MCP server: jimeng4-mcp

📦 安装

1. 全局安装（推荐）

npm install -g volcengine-imagegen-mcp

2. 使用 npx 运行（无需安装）

npx volcengine-imagegen-mcp

🔑 配置 API Key

在使用之前，需要设置火山引擎 API Key：

Windows

set ARK_API_KEY=你的火山引擎API密钥

PowerShell

$env:ARK_API_KEY="你的火山引擎API密钥"

Linux/macOS

export ARK_API_KEY="你的火山引擎API密钥"

如何获取 API Key？

  1. 访问 火山方舟控制台

  2. 登录火山引擎账号

  3. 创建 API Key

  4. 复制 API Key 并设置环境变量

💡 配置方式说明： 不同应用的配置格式略有不同：

  • Claude Code/Claude Desktop: 使用 "mcpServers" 键，配置简单（见下方）

  • VS Code: 使用 "servers" 键，需要指定 "type": "stdio"（见下方）

  • Cursor/Trae: 配置格式类似 Claude Code/Claude Desktop

🚀 使用方法

在 Claude Code / Claude Desktop 中使用

  1. 打开 Claude Code 或 Claude Desktop 设置

  2. 找到 MCP Servers 配置项

  3. 添加新服务器：

    • 名称: volcengine-imagegen-mcp

    • 命令: npx volcengine-imagegen-mcp

    • 环境变量: ARK_API_KEY=你的API密钥

  4. 保存配置并重启应用

在 VS Code 中使用

  1. 确保已安装 VS Code 1.102 或更高版本

  2. 在工作区根目录创建 .vscode/mcp.json 文件

  3. 添加以下配置：

    {
  "servers": {
    "volcengine-imagegen": {
      "type": "stdio",
      "command": "npx",
      "args": ["volcengine-imagegen-mcp"],
      "env": {
        "ARK_API_KEY": "你的API密钥"
      }
    }
  },
  "inputs": []
}

  4. 重新加载 VS Code 窗口（Ctrl+Shift+P → "Developer: Reload Window"）

  5. 打开 Copilot Chat（Ctrl+Alt+I），在工具选择器中启用 volcengine-imagegen 服务器的工具

💡 工具选择说明： VS Code 中有两种方式管理 MCP 工具：

  1. 工具选择器按钮：在 Chat 输入框上方点击工具图标（🛠️），可以单独启用/禁用每个工具

  2. Chat 输入中指定：在提示中直接引用工具，如 #generate_image

  3. 全局配置：在设置中通过 chat.mcp.enabledServers 控制哪些服务器可用

使用示例：

  • 禁用所有工具后只使用 #generate_image 和 #list_models

  • 或通过工具选择器只勾选 generate_image 相关工具

💡 详细配置说明请查看 VS Code 配置指南

在 Cursor 中使用

  1. 打开 Cursor 设置

  2. 找到 MCP 配置

  3. 添加服务器：

    {
  "name": "volcengine-imagegen",
  "command": "npx",
  "args": ["volcengine-imagegen-mcp"],
  "env": {
    "ARK_API_KEY": "你的API密钥"
  }
}

在 Trae 中使用

Trae 原生支持火山引擎 MCP 服务，可以直接在火山引擎 MCP 市场中选择使用。

🛠️ 可用工具

1. generate_image - 文生图

根据文本提示词生成图片。

参数:

  • model (string): 模型 ID，默认 "doubao-seedream-4.5"

  • prompt (string): 图片生成提示词（支持中英文）

  • size (string): 图片尺寸，默认 "2K"（支持：2K, 4K, 1024x1024, 2048x2048）

  • guidance_scale (number): 文本权重（1-10），默认 2.5

  • response_format (string): 返回格式，默认 "url"（支持：url, b64_json）

  • watermark (boolean): 是否添加水印，默认 false

  • count (number): 生成图片数量（1-4张），默认 1

示例提示:

生成一张充满活力的特写肖像，模特眼神犀利

2. image_to_image - 图生图

根据参考图片和文本提示词生成新图片。

参数:

  • model (string): 模型 ID，默认 "doubao-seedream-4.5"

  • prompt (string): 图片生成提示词

  • image_urls (array): 参考图片 URL 列表（最多14张）

  • size (string): 图片尺寸，默认 "2K"

  • guidance_scale (number): 文本权重（1-10），默认 2.5

  • response_format (string): 返回格式，默认 "url"

  • watermark (boolean): 是否添加水印，默认 false

示例提示:

根据这张图片的风格，生成一张新的城市夜景照片
[上传参考图片]

3. generate_image_set - 组图生成

生成一组内容关联的图片（最多15张）。

参数:

  • model (string): 模型 ID，默认 "doubao-seedream-4.5"

  • prompt (string): 图片生成提示词

  • count (number): 生成图片数量（2-15张），默认 4

  • size (string): 图片尺寸，默认 "2K"

  • guidance_scale (number): 文本权重（1-10），默认 2.5

  • response_format (string): 返回格式，默认 "url"

  • watermark (boolean): 是否添加水印，默认 false

示例提示:

生成一组4张科幻风格的太空探索主题插画

4. list_models - 获取模型列表

获取所有支持的模型及其说明。

📋 支持的模型

模型 ID

说明

支持的功能

doubao-seedream-4.5

豆包生图 4.5（最新）

✅ 文生图 ✅ 图生图 ✅ 组图 ✅ 多图生图

doubao-seedream-4.0

豆包生图 4.0

✅ 文生图 ✅ 图生图 ✅ 组图 ✅ 多图生图

doubao-seedream-3.0-t2i

豆包生图 3.0 文生图

✅ 仅文生图

doubao-seedream-3.0-i2i

豆包生图 3.0 图生图

✅ 仅图生图

📸 快速开始

1️⃣ 安装

npm install -g volcengine-imagegen-mcp

2️⃣ 配置 API Key

访问 火山方舟控制台 获取 API Key，然后设置环境变量：

# Windows PowerShell
$env:ARK_API_KEY="your-api-key-here"

# Linux/macOS
export ARK_API_KEY="your-api-key-here"

3️⃣ 配置 Claude Desktop

编辑 Claude Desktop 配置文件（claude_desktop_config.json）：

{
  "mcpServers": {
    "volcengine-imagegen": {
      "command": "npx",
      "args": ["volcengine-imagegen-mcp"],
      "env": {
        "ARK_API_KEY": "your-api-key-here"
      }
    }
  }
}

4️⃣ 开始创作

重启 Claude Desktop，然后直接对话：

  • "帮我生成一只赛博朋克风格的猫"

  • "根据这张照片生成卡通版本"

  • "生成一组 4 张太空主题插画"

⚙️ 高级配置

环境变量

变量名

说明

必需

ARK_API_KEY

火山引擎 API 密钥

✅ 是

返回格式选择

  • url: 返回图片下载链接（24小时内有效）

  • b64_json: 直接返回 Base64 编码的图片数据

建议：

  • 需要快速预览或嵌入应用 → 使用 b64_json

  • 需要高质量下载或长期保存 → 使用 url

🎯 使用建议

提示词编写技巧

  1. 详细描述: 包含主体、风格、颜色、构图等要素

  2. 中英文混合: 模型对中英文都有良好理解能力

  3. 风格指定: 明确指定想要的风格（如"写实风格"、"动漫风格"等）

  4. 质量关键词: 添加"高清"、"4K"、"专业"等关键词提升质量

参数调优建议

参数

低值

高值

效果

guidance_scale

1-3

7-10

低值更自由创作，高值更严格遵循提示词

size

2K, 1024x1024

4K, 2048x2048

大尺寸需要更多时间和算力

成本控制

  • 图片链接 24小时后失效，请及时下载

  • 组图生成（15张）需要较长时间，建议先用少量测试

  • 4K 分辨率生成成本高于 2K

💡 使用示例

📝 文生图示例

用户: 帮我生成一张照片，内容是日落时分的埃菲尔铁塔，背景是巴黎城市景观
Claude: [调用 generate_image 工具]
✓ 生成完成！图片包含金色的阳光洒在埃菲尔铁塔上...

🖼️ 图生图示例

用户: [上传一张风景照]
用户: 把这张照片改成宫崎骏动画风格
Claude: [调用 image_to_image 工具]
✓ 转换完成！已将照片转换为温馨的吉卜力动画风格...

🎨 组图生成示例

用户: 帮我设计一套猫咪主题的表情包，要 6 张不同表情
Claude: [调用 generate_image_set 工具，count=6]
✓ 已生成 6 张猫咪表情包：开心、生气、惊讶、卖萌、睡觉、思考...

🎯 应用场景

  • 内容创作: 快速生成配图、插画、海报素材

  • 设计灵感: 探索不同的视觉风格和创意方向

  • 图片编辑: 风格迁移、图片重绘、创意合成

  • 原型设计: 为产品快速生成视觉概念图

  • 教育培训: 生成教学插图和示例图片

🔧 开发

构建

npm install
npm run build

本地运行

npm run start

开发模式

npm run dev

📄 许可证

MIT © fucheng830

🤝 贡献

欢迎提交 Issue 和 Pull Request！

  1. Fork 本仓库

  2. 创建特性分支 (git checkout -b feature/AmazingFeature)

  3. 提交更改 (git commit -m 'Add some AmazingFeature')

  4. 推送到分支 (git push origin feature/AmazingFeature)

  5. 开启 Pull Request

📞 支持

🔗 相关链接

🔗 相关链接

⭐ Star History

如果这个项目对你有帮助,请给个 Star 支持一下！

Available Tools

4 tools
generate_imageA

生成图片（文生图）。使用文字描述生成一张图片。

ParametersJSON Schema
NameRequiredDescriptionDefault
sizeNo图片尺寸2K
countNo生成图片数量（当前仅支持1张）
modelNo使用的模型IDdoubao-seedream-4-5-251128
promptYes图片生成提示词（支持中英文）
watermarkNo是否添加水印
guidance_scaleNo文本权重（1-10）
response_formatNo响应格式：url 或 b64_jsonurl

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states that the tool generates an image from text, but does not disclose output format, default watermark behavior, model behavior, or any side effects. Minimal behavioral detail beyond the tool's name.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise, consisting of two short sentences. The second sentence adds useful detail (text input and single image output) rather than repeating the first. No wasted words or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 7 parameters, no output schema, and no annotations, yet the description provides no guidance on result format, how to configure size or model, or when to prefer sibling tools. It only explains the basic operation, which is insufficient for a tool with this many configurable options.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage with per-parameter explanations, so the baseline is 3. The description adds no parameter-specific guidance beyond indicating that a text prompt is used, which the schema already documents.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb+resource: '生成图片' (generate image) and explicitly says '使用文字描述生成一张图片' (use text description to generate one image). This differentiates the tool from siblings like image_to_image by specifying text input, and from generate_image_set by specifying a single image.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context that this tool is for text-to-image generation from a text prompt, implying it should be used when the user has a textual description and wants a single image. However, it does not explicitly name alternatives or advertise when not to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_image_setB

批量生成图片。生成多张内容相关的图片（通过多次调用实现）。

ParametersJSON Schema
NameRequiredDescriptionDefault
sizeNo图片尺寸2K
countYes生成图片数量（2-15张）
modelNo使用的模型IDdoubao-seedream-4-5-251128
promptYes图片生成提示词
guidance_scaleNo文本权重
response_formatNo响应格式url

TDQS

B3.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses a useful behavioral trait: the operation is implemented through multiple underlying calls. However, with no annotations provided, it fails to mention potential side effects, failure modes, cost, rate limits, or how results are aggregated/returned.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with two sentences, each adding value. It is front-loaded but lacks structural organization; a bit more context would make it more useful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 6 parameters, no output schema, and no annotations, this description is insufficient. It does not explain return value handling, batching error behavior, or relationships to sibling tools, leaving significant gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema fully documents all six parameters. The description adds no additional parameter-level detail beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: batch-generating multiple content-related images. It distinguishes from sibling tools by emphasizing 'multiple' and 'content-related', though it does not explicitly name alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for batch generation of related images, but provides no explicit guidance on when to choose this tool versus generate_image or image_to_image. No exclusions, prerequisites, or scenario examples are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

image_to_imageB

图生图。基于参考图片生成新图片。

ParametersJSON Schema
NameRequiredDescriptionDefault
sizeNo图片尺寸2K
modelNo使用的模型ID（仅支持 4.5/4.0）doubao-seedream-4-5-251128
promptYes图片生成提示词
image_urlsYes参考图片 URL 列表（最多14张）
guidance_scaleNo文本权重
response_formatNo响应格式url

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the core function and does not mention constraints like URL accessibility, model compatibility, output format behavior, or any rate/cost considerations. The schema provides some parameter details but the description itself adds little behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise, using a single short sentence after the initial '图生图' label. It is front-loaded and wastes few words, though it may be overly terse given the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 6 parameters, no output schema, no annotations, and sibling tools for comparison, the description is too minimal to be fully contextually complete. It lacks guidance on expected outputs, when to choose this tool, or how the generation behaves with multiple reference images.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema adequately documents all parameters. The description adds no semantic value beyond the schema, only reinforcing the 'reference images' concept already captured by image_urls. This meets the baseline but does not exceed it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool's action: '图生图。基于参考图片生成新图片' (image-to-image, generate a new image based on reference images). It specifies both the resource (reference images) and the verb (generate), and the reference-image basis distinguishes it from sibling tools like generate_image.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied: it is for generating images from reference images. However, there is no explicit guidance on when to use this tool versus alternatives such as generate_image or generate_image_set, and no mention of when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_modelsA

获取支持的模型列表和功能说明

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It only restates the function implied by the name and does not disclose behavioral traits such as read-only safety, output format, side effects, or any prerequisites. It adds little beyond the obvious.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise phrase with no wasted words. It is appropriately sized for a parameterless query tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (no parameters, no annotations, no output schema), the description gives a high-level summary but lacks detail about the exact return structure or how the model list connects to sibling tools. It is adequate but not complete for an agent needing to use the output.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the baseline is 4. The description does not need to explain parameter semantics, and there is no schema to compensate for, making this baseline appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves a list of supported models with feature descriptions, using a specific verb ('获取') and resource ('支持的模型列表和功能说明'). This distinguishes it from sibling tools that generate or transform images.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage context is implied: it's a query tool that likely provides model selection info for the sibling generation tools. However, there is no explicit statement about when to use it or how it relates to alternatives, missing a clear when-to-use/when-not-to-use directive.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 4 tool updatesv1.0.1
    • First observedgenerate_image
    • First observedgenerate_image_set
    • First observedimage_to_image
    • First observedlist_models
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.6/5.0

Scored across 4 tools

Disambiguation4/5

Most tools are clearly distinct: generate_image handles text-to-image, image_to_image handles image-to-image, and list_models provides model metadata. However, generate_image_set overlaps with generate_image since it is described as generating multiple related images via repeated calls, potentially causing occasional misselection.

Naming Consistency3/5

Tool names mix conventions: generate_image and generate_image_set follow a verb_noun pattern, list_models also follows verb_noun, but image_to_image uses a noun_to_noun structure. This inconsistency is noticeable but still readable and understandable.

Tool Count5/5

With only 4 tools, the server is well-scoped for an image generation service. Each tool serves a clear purpose without unnecessary bloat, and the count aligns well with the domain.

Completeness4/5

The tool surface covers core image generation workflows: text-to-image, image-to-image, batch generation, and model discovery. Minor gaps exist, such as lack of explicit image variation or style transfer, but these are not critical and can be worked around with existing tools.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers