volcengine-ark-mcp

调用火山方舟（Volcengine Ark）的 MCP server：Seedream 5.0 生成和编辑图片、Seedance 视频、对话与多模态理解、联网搜索和向量化，产物直接存到本地。

原名 seedream-mcp（PyPI 上该名已被他人占用），0.4 起改名，不保留旧命令和 SEEDREAM_* 环境变量。

0.6.0 去掉 query_video：视频进度统一用 get_job(job_id=...) 或 get_job(task_id=...) 查询，完成时自动下载；generate_image 新增 parameters。这是不兼容变更。

Seedream 图片生成

三个模型都支持文生图和单图 / 多图参考生图。模型不支持的参数组合会在本地直接报错，不发请求。

环境变量

参数说明见工具描述（src/volcengine_ark_mcp/server.py），接口细节以图片生成 API 文档为准。

0.3 方舟扩展（待云端验证）

保留原有生图工具，同时接入方舟其他能力，无需新建MCP配置。

Seedance视频

模型别名：seedance → doubao-seedance-2-5-260628；seedance-2 / seedance-fast / seedance-mini → 相应2.0系列。 也可直接指定完整模型ID或Endpoint ID。不同模型的素材数量、时长、分辨率限制以官方接口为准。

默认 wait=0，提交后返回 task_id、job_id。get_job(job_id=..., wait=30) 查询进度，完成后下载到原目录；别处提交的任务可传 get_job(task_id=...)，首次查询会新建本地记录。下载失败或链接过期用 recover_job(job_id=...)。都不会提交新生成。

图片支持本地路径/data URL/公网URL；视频和音频参考使用公网URL或 asset:// ID。本轮没有自动上传本地视频/音频。 2.5首帧/首尾帧任务 ratio=adaptive；输出时长为4–30秒，2.0系列为4–15秒，均可用 duration=-1。首尾帧与全模态参考不能混用；2.0系列不能仅传音频。 2.0标准版支持4k，fast/mini仅480p/720p。视频编辑通过prompt明确意图，duration=-1、ratio=adaptive；可用 parameters.omni_reference_task_type="edit" 提前校验任务类型，省略duration采用官方默认值。 parameters 可传官方顶层选项，如 draft、return_last_frame、output_format；不能覆盖模型和输入素材。

对话与检索

chat 默认 pro 为 doubao-seed-2-1-pro-260628，也可显式指定模型；与生图工具中的pro别名含义不同。 images 支持本地图片，videos 须公开URL。不开搜索时使用Chat API；开启 web_search 或提供 previous_response_id 时使用Responses API。 多轮历史采用Chat消息结构，Responses会转换本轮多模态内容；保留 response_id、来源注解；完整响应用 include_response=true 按需获取。 parameters 透传模型支持的高级选项，不执行模型返回的工具调用。

向量工具须显式指定模型：texts 为文本列表；contents 为官方类型化数组，例如：

[{"type":"text","text":"猫"},{"type":"image_url","image_url":{"url":"/absolute/cat.png"}}]

返回 data、usage，完整响应用 include_response=true 按需获取；不自动建索引或知识库。

本地恢复

ARK_JOB_DIR 默认 ~/.local/share/volcengine-ark-mcp/jobs。生成前创建记录，响应收到后保留完整响应，内联图片先缓存再交付。 组图逐项记录错误，下载失败可单独补交付；图层记录和 layers.json 随恢复更新。部分生成失败会返回 partial，不会重新生成失败项。 视频保存原 task_id，通过云端查询刷新URL。临时URL或云端任务过期可能无法恢复。

返回 job_id、job_state、request_id 和 artifacts。ok 表示本次调用成功；已提交、运行中返回 ok=true, completed=false，全部交付返回 completed=true，执行错误通过 MCP isError=true 返回。 get_job.ok 是记录读取成功；调用超时没拿到ID时可用 list_jobs 按时间查找。保留原有files、layers、usage、errors字段。 每项产物记录字节数和SHA-256；下载采用临时文件和原子替换。质量、像素尺寸和媒体播放仍需后续验证。

url模式也留存任务元数据；任务目录保存签名URL、响应与图片缓存，不保存API Key。缓存用于恢复，不自动清理。 恢复锁使用POSIX flock，面向macOS/Linux。产物默认目录增加随机后缀，避免同秒调用碰撞。

原始接入范围见 接入记录。当前运行时和任务恢复已通过离线故障测试及真实 stdio 检查；尚未验证云端生成、账号权限和媒体质量。

产物的 media_info 读取PNG头中的实际宽高；若系统已有 ffprobe，可读取其他媒体的实际尺寸、时长和音轨信息。不可读取时显式返回 available=false，不把请求参数当作实际输出规格。无需新增Python依赖。

运行时与稳定性

共享连接池、总超时、工具分组、错误语义和迁移说明见 MCP 构建与稳定性。完整工具说明可调用 get_tool_help(tool="工具名")。

官方接口核实

逐工具映射、模型版本、参数差异和可程序化获取的官方文档来源见 火山方舟接口审计。本地校验依据2026-10-10官方文档快照；账号权限及实际云端生成仍未验证。