MCP Multimedia Server

给 LLM agent(Claude Code / Codex 等)外挂小米 MiMo V2.5 的多模态理解能力——图片、视频、纯音频、语音转写(ASR),全部走云端 MiMo V2.5 完成,本地只做必要的预处理(图片压缩、视频重编码)以省 token / 控制体积。

MCP(MCP = Model Context Protocol)stdio 服务器,注册进 agent 后即可当工具直接调用。

用途

• 图片理解 / OCR:单张或批量(一次最多 100 张,适合文档逐页解析)
• 视频理解:本地视频自动压缩重编码后发送,fps 可调精细度
• 音频理解 / STT:转录或总结一段语音
• 语音转写(ASR):纯转写,支持语种指定
• 底层统一使用 MiMo V2.5(原生多模态,1M 上下文),通过任意 OpenAI 兼容端点接入

工具

工具	输入	说明
analyze_image	image(单张)或 image_batch(批量数组)	描述/OCR/图表/UI/报错诊断;本地图片默认压缩(8MP 上限 + A4-OCR 分辨率,compress=false 可关);批量最多 100 张
analyze_video	video + fps(1-30)	本地视频自动重编码(短边 720p);支持 URL
analyze_audio	audio	音频理解/STT(转录+总结);推荐本地文件或 base64
asr	audio + language(auto/zh/en)	纯语音转写;仅 wav/mp3,≤10MB
image_metadata	本地路径	读取图片尺寸/格式/EXIF/GPS,不调用云端
get_server_status	—	查看当前模型与各项限制/参数

工作原理

agent ── MCP stdio ──> 本服务 ── OpenAI 兼容端点 ──> MiMo V2.5(云端)
                        │
                        ├─ 图片:本地压缩(8MP 上限 + A4-OCR 分辨率)→ image_url
                        ├─ 视频:ffmpeg 重编码(短边720p + fps)→ video_url
                        └─ 音频:本地/base64 → input_audio(data + format)

• 本地处理仅在发送前预处理,不做任何媒体理解
• 所有推理/识别/转写在云端 MiMo V2.5 完成
• 上下文窗口 1M tokens;媒体按分辨率/时长计 token(压缩后 A4 图约 1.8K token/张)

环境要求

• Python 3.10+
• ffmpeg(视频重编码用,须在 PATH)
• 一个 OpenAI 兼容的多模态端点 + API key(如小米 MiMo 官方 api.xiaomimimo.com,或任意代理网关)

安装

# 1. 建 venv 并从 GitHub 安装
uv venv ~/.local/venvs/mcp-multimedia-server
uv pip install --python ~/.local/venvs/mcp-multimedia-server \
    git+https://github.com/ThermalEng/mcp-multimedia-server.git

# 2. ffmpeg(视频重编码)
sudo apt install ffmpeg

配置

操作参数(大小上限、压缩目标、视频重编码、格式白名单等)硬编码在 mcp_multimedia_server/config.py,改代码即可调整。上游三件套从进程环境读取:

环境变量	说明
MCP_MEDIA_BASE_URL	OpenAI 兼容端点(默认 https://opencode.ai/zen/go/v1)
MCP_MEDIA_API_KEY	API key(不写进代码/仓库,只放环境)
MCP_MEDIA_MODEL	模型名(默认 mimo-v2.5)

Claude Code 注册(stdio)

把下面合并到 ~/.claude.json 的 mcpServers:

{
  "mcpServers": {
    "multimedia": {
      "type": "stdio",
      "command": "~/.local/venvs/mcp-multimedia-server/bin/mcp-multimedia-server",
      "args": [],
      "env": {
        "MCP_MEDIA_BASE_URL": "https://opencode.ai/zen/go/v1",
        "MCP_MEDIA_API_KEY": "sk-你的key",
        "MCP_MEDIA_MODEL": "mimo-v2.5"
      }
    }
  }
}

注册后重启 agent,即可用 analyze_image / analyze_video / analyze_audio / asr 等工具。

备注

• 依赖 mcp SDK 须钉在 <2(SDK 2.x 移除了 Server.list_tools 装饰器)
• 视频重编码依赖系统 ffmpeg(config.VIDEO_FFMPEG 可指绝对路径)
• 专用模型说明:mimo-v2.5-asr / mimo-v2.5-tts 为官方独立模型;若你的端点未开放它们(部分网关 401),ASR 会用 mimo-v2.5 顶替(仍可转写),TTS 则不可用
• 流式/SSE 传输:MCP_TRANSPORT=sse / MCP_PORT=8093(需 pip install mcp-multimedia-server[sse])