mcp-media-toolbox

一个零依赖的 MCP 服务器：媒体元数据探测 / AAC 音轨直抽 / EXIF 读取。不需要 ffmpeg，不需要 Python。

A zero-dependency MCP server for media probing, AAC extraction and EXIF — no ffmpeg, no Python. Runs where you cannot install binaries: Android app sandboxes, Termux, minimal containers.

整个 server 只 import 4 个 Node 内置模块（fs / os / crypto / readline）， npm install 什么都不装，node server.mjs 直接跑。

为什么会有这个

主流媒体工具都依赖 ffmpeg/ffprobe。但在受限环境里（Android 应用私有目录禁止执行二进制、 无 root、无 Python、容器里不想装 100 MB 依赖），这条路直接断掉。

这个项目把最常用的三件事用纯 JS 重写：

Related MCP server: image-analysis-mcp

快速开始

git clone https://github.com/Verchiel666/mcp-media-toolbox.git && cd mcp-media-toolbox
npm run fixtures      # 生成合成测试素材（仓库里没有第三方二进制）
npm run selftest      # 21 项断言，退出码 0 = 全过
node client.mjs --demo

接进任何 MCP 客户端（Claude Desktop / Cursor / 自研）：

{
  "mcpServers": {
    "media-toolbox": {
      "command": "node",
      "args": ["/absolute/path/to/server.mjs"]
    }
  }
}

已发布到 npm，可以直接用 npx（无需 clone）：

{
  "mcpServers": {
    "media-toolbox": {
      "command": "npx",
      "args": ["-y", "mcp-media-toolbox"]
    }
  }
}

npx -y mcp-media-toolbox   # 直接作为 stdio server 启动

工具

全部只读，或只新增输出文件，不修改、不删除源文件。

实测数据

在 Android 15（arm64，Node v24.22.1，无 ffmpeg）上：

selftest.mjs 用合成素材跑同样的断言，所以 CI 不需要任何外部文件。

已知限制（诚实清单）

• 只解析带 moov 的 ISO-BMFF；碎片化 mp4 / fMP4 / MKV / 裸流一律明确报错，不假装成功。

• 只直抽 AAC（mp4a）；Opus / AC-3 / ALAC 不支持。不做重采样、不转 WAV。

• HE-AAC（SBR/PS）会被当成 AAC-LC 写 ADTS 头：能播，但采样率标注可能偏低。

• EXIF 仅 JPEG；PNG/HEIC 未实现。

• find_duplicates 对超大目录只做有界扫描（默认 3000 文件），返回里有 truncated 标记。

三个必踩的坑（experiments/ 可复现）

写 MCP server 时最容易在这三处翻车，详见 docs/mcp-notes.md：

1. 工具里一句 console.log 污染 stdout → 客户端 JSON 解析当场崩。

2. 美化输出（JSON.stringify(x, null, 2)）把一个消息拆成多行，同样违规，而且症状只是「没反应」。

3. 握手顺序错（缺 notifications/initialized）→ 客户端无限转圈。

node client.mjs --list --server experiments/server-pretty.mjs   # 看它怎么炸

在 DSH（Android）里挂本地 server

DSH 引擎自带 @deepseek-ai/dsh-mcp-client，但 App 的设置页只接受远程 HTTP / npm 包， 拒绝本地 node script.mjs 这种写法。可行方式与踩坑记录见 docs/dsh-android.md。

在 npm 上

mcp-media-toolbox —— 只发布 server.mjs 与文档，测试素材不进包（21.6 KiB）。

相关

同源的姊妹项目：DSH（本项目的 MCP 桥接就是在它上面验证的）。

License

MIT