Skip to content
Back to search

volcengine-ark-media-mcp

火山方舟 Agent Plan 媒体 MCP Server。通过 MCP 工具调用:

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mrlinwang--volcengine-ark-media-mcp/badge.svg)](/listings/mrlinwang--volcengine-ark-media-mcp)

HTML

<a href="/listings/mrlinwang--volcengine-ark-media-mcp"><img src="/api/listings/mrlinwang--volcengine-ark-media-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 218 lines
  1. # volcengine-ark-media-mcp
  2. 火山方舟 Agent Plan 媒体 MCP Server。通过 MCP 工具调用:
  3. - 图片生成:Seedream 5.0 Pro / 5.0 Flash
  4. - 视频生成:Seedance 2.5 / 2.0 系列(任务创建、查询、等待、列表、取消/删除)
  5. - 语音合成:豆包语音合成 2.0
  6. - 语音识别:豆包流式语音识别 2.0
  7. > Agent Plan Medium 支持图片、TTS、ASR,不支持视频;视频工具会返回明确的套餐提示。
  8. ## 工具
  9. | 工具 | 作用 |
  10. | --- | --- |
  11. | `ark_generate_image` | 文生图、单图/多图生图,返回图片 URL |
  12. | `ark_create_video_task` | 创建视频生成任务 |
  13. | `ark_get_video_task` | 查询任务状态和视频 URL |
  14. | `ark_wait_video_task` | 轮询等待任务结束 |
  15. | `ark_list_video_tasks` | 分页列出任务 |
  16. | `ark_delete_video_task` | 取消排队任务或删除任务 |
  17. | `ark_text_to_speech` | 文本转语音,保存文件并返回音频内容 |
  18. | `ark_speech_to_text` | 音频转文本,支持常见格式 |
  19. | `ark_list_models` | 列出模型、默认值和套餐限制 |
  20. ## 快速开始
  21. ```powershell
  22. npm install
  23. Copy-Item .env.example .env
  24. # 编辑 .env,填入 ARC_AGENT_PLAN_KEY
  25. npm run build
  26. node --env-file=.env dist/index.js
  27. ```
  28. 本地调试也可以直接:
  29. ```powershell
  30. npm run dev
  31. ```
  32. ## MCP 客户端配置
  33. ### Codex
  34. 在 `~/.codex/config.toml` 中加入:
  35. ```toml
  36. [mcp_servers.volcengine-ark-media-mcp]
  37. command = "node"
  38. args = ["E:\\Codes\\arc-agent-media-mcp\\dist\\index.js"]
  39. env = { ARC_AGENT_PLAN_KEY = "你的 Agent Plan API Key" }
  40. ```
  41. ### Claude Code / Claude Desktop
  42. ```json
  43. {
  44. "mcpServers": {
  45. "volcengine-ark-media-mcp": {
  46. "command": "node",
  47. "args": ["E:\\Codes\\arc-agent-media-mcp\\dist\\index.js"],
  48. "env": {
  49. "ARC_AGENT_PLAN_KEY": "你的 Agent Plan API Key"
  50. }
  51. }
  52. }
  53. }
  54. ```
  55. ### 通过 npx(npm 包发布后)
  56. ```json
  57. {
  58. "mcpServers": {
  59. "volcengine-ark-media-mcp": {
  60. "command": "npx",
  61. "args": ["-y", "volcengine-ark-media-mcp"],
  62. "env": {
  63. "ARC_AGENT_PLAN_KEY": "你的 Agent Plan API Key"
  64. }
  65. }
  66. }
  67. }
  68. ```
  69. ## 在 magpie 中本地安装
  70. 已发布到 npm 与官方 MCP Registry,可以直接用 npm 包安装:
  71. ```json
  72. {
  73. "mcpServers": {
  74. "volcengine-ark-media-mcp": {
  75. "command": "npx",
  76. "args": ["-y", "volcengine-ark-media-mcp"],
  77. "env": { "ARC_AGENT_PLAN_KEY": "你的 Agent Plan API Key" }
  78. }
  79. }
  80. }
  81. ```
  82. 也可以继续用本地仓库的 wrapper 安装:
  83. ```powershell
  84. magpie library mcp add volcengine-ark-media-mcp node E:\Codes\arc-agent-media-mcp\scripts\run-local.mjs agents=codex
  85. magpie library sync
  86. ```
  87. > 上面的 `E:\Codes\arc-agent-media-mcp` 是本机示例路径;请替换成你实际 clone 的仓库目录。
  88. `scripts/run-local.mjs` 会从仓库根目录的 `.env` 读取 `ARC_AGENT_PLAN_KEY`,再启动 `dist/index.js`。Windows 下也可以直接用 `scripts\run-local.cmd`。
  89. 也可以在 magpie 的 **Library → MCP servers → 添加** 中填写:
  90. - Command: `node`
  91. - Args: `E:\Codes\arc-agent-media-mcp\dist\index.js`
  92. - Environment: `ARC_AGENT_PLAN_KEY=你的 Agent Plan API Key`
  93. 如果 magpie 已经在运行,命令行添加后需要重启一次 magpie,让运行中的网关加载新 server;只重启 Codex 不够。通过 magpie GUI 添加则不需要重启。安装后重启对应 agent,让 magpie 写入的 MCP 配置生效。
  94. ## 配套 Skill
  95. 仓库包含 `skills/volcengine-ark-media-mcp/SKILL.md`,用于教 agent 在图片、视频、TTS、ASR 场景中选择正确的 `ark_*` 工具,并处理套餐限制、媒体 URL 过期和本地文件输入。
  96. 安装到 Codex:
  97. ```powershell
  98. Copy-Item -Recurse -Force .\skills\volcengine-ark-media-mcp "$HOME\.codex\skills\volcengine-ark-media-mcp"
  99. ```
  100. 在 magpie 中可从本仓库的 `skills/volcengine-ark-media-mcp` 安装该 Skill。
  101. ### magpie 市场
  102. magpie 的 MCP 市场搜索来自官方 MCP Registry。本包已发布为
  103. `io.github.MrLinWang/volcengine-ark-media-mcp@1.0.0`,在 magpie 中搜索 `volcengine` 或 `ark` 即可看到并安装。发布新版本的步骤见 [PUBLISHING.md](PUBLISHING.md)。
  104. ## 环境变量
  105. | 变量 | 必填 | 默认值 |
  106. | --- | --- | --- |
  107. | `ARC_AGENT_PLAN_KEY` | 是 | — |
  108. | `ARK_API_KEY` | 兼容别名 | — |
  109. | `ARK_BASE_URL` | 否 | `https://ark.cn-beijing.volces.com/api/plan/v3` |
  110. | `ARK_TTS_BASE_URL` | 否 | `https://openspeech.bytedance.com/api/v3/plan` |
  111. | `ARK_ASR_BASE_URL` | 否 | `wss://openspeech.bytedance.com/api/v3/plan/sauc` |
  112. | `ARK_TTS_RESOURCE_ID` | 否 | `seed-tts-2.0` |
  113. | `ARK_ASR_RESOURCE_ID` | 否 | `volc.seedasr.sauc.duration` |
  114. | `ARK_IMAGE_MODEL` | 否 | `doubao-seedream-5-0-pro` |
  115. | `ARK_VIDEO_MODEL` | 否 | `doubao-seedance-2.0` |
  116. | `ARK_TTS_SPEAKER` | 否 | `zh_female_gaolengyujie_uranus_bigtts` |
  117. | `ARK_MEDIA_OUTPUT_DIR` | 否 | `~/.arc-agent-media-mcp/outputs` |
  118. | `ARK_REQUEST_TIMEOUT_MS` | 否 | `180000` |
  119. | `ARK_PLAN_TIER` | 否 | `unknown`;可选 `small`、`medium`、`large`、`max` |
  120. | `ARK_DEBUG` | 否 | `0`;设为 `1` 输出调试日志 |
  121. ## 套餐等级配置
  122. 套餐等级本身由火山方舟账号里的 Agent Plan 订阅决定,MCP 不能修改;每个用户使用自己的 `ARC_AGENT_PLAN_KEY`,该 Key 所属的订阅就是实际套餐等级。
  123. `ARK_PLAN_TIER` 只是 MCP 侧的本地提示/提前校验开关,不会改变实际权限:
  124. - 设置为 `medium` 或 `small`:`ark_list_models` 会标记视频模型不可用,`ark_create_video_task` 会在调用 API 前直接返回“需要 Large/Max”的错误。
  125. - 设置为 `large` 或 `max`:视频工具正常调用。
  126. - 不设置或设置为 `unknown`:不提前判断,由火山方舟 API 的实际返回决定(Medium 会返回 `UnsupportedModel`)。
  127. 示例:
  128. ```powershell
  129. # .env
  130. ARC_AGENT_PLAN_KEY=你的 Key
  131. ARK_PLAN_TIER=medium
  132. ```
  133. 如果升级了套餐,记得把 `ARK_PLAN_TIER` 改成 `large`/`max`,或删除该变量。
  134. ## 使用示例
  135. 生成图片:
  136. > 用 ark_generate_image 生成一张 1K 的赛博朋克猫咪图片,提示词:……
  137. 生成视频(需要 Large/Max):
  138. > 用 ark_create_video_task 创建 5 秒 16:9 视频,然后立刻用 ark_wait_video_task 等待完成。
  139. 语音合成:
  140. > 用 ark_text_to_speech 把“你好,欢迎使用火山方舟”合成成 mp3。
  141. 语音识别:
  142. > 用 ark_speech_to_text 转写 `C:\audio\meeting.mp3`。
  143. ## 注意事项
  144. - 图片和视频 URL 有效期为 24 小时,请及时转存。
  145. - 视频参考视频只支持公网 URL 或 `asset://` 素材 ID;本地视频需先上传。
  146. - TTS 输出默认保存到 `~/.arc-agent-media-mcp/outputs`,同时以 MCP audio content 返回。
  147. - ASR 非 WAV 文件会通过内置 `ffmpeg-static` 转为 16k 单声道 WAV。
  148. - 所有工具都会消耗 Agent Plan 额度。
  149. ## 测试
  150. ```powershell
  151. npm run build
  152. npm test
  153. npm run smoke:mcp
  154. npm run smoke:magpie
  155. $env:RUN_LIVE="1"; npm run smoke:live
  156. ```
  157. `smoke:magpie` 需要 magpie 已重启并加载本 server;`smoke:live` 会调用真实的图片、TTS、ASR,并在 Medium 套餐上验证视频返回 `UnsupportedModel`。
  158. ## License
  159. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.