mcp-qmedia

自编写的 MCP 服务器，让纯文本代理能够询问媒体问题——图片、音频、视频。代理传递文件路径（或 URL）加上一个问题；服务器将其发送到 Xiaomi MiMo-V2.5（原生全模态：文本/图片/音频/视频输入，文本输出），通过 OpenCode Zen 端点，并将答案作为文本返回。可从 opencode 和 Claude Code 中使用。

提供商

所有提供商使用相同的代码路径（兼容 OpenAI 的 /chat/completions，base64 内容部分）。内置两个；可以在 Web UI（见下文）中添加、删除和切换默认提供商——或通过编辑存储文件 ~/.config/mcp-qmedia/providers.json（0600 权限，位于仓库外；可能包含密钥）。每次调用：backend="<name>"；QMEDIA_BACKEND 覆盖存储的默认值。

Related MCP server: Vision MCP Server

API 密钥——绝不在此仓库中

每个提供商，解析顺序：提供商在存储中的自有密钥（通过 UI 设置）→ QMEDIA_API_KEY → OPENCODE_API_KEY → ~/.local/share/opencode/auth.json（QMEDIA_AUTH_JSON）：提供商的 auth_entry，然后是任何其他包含密钥的条目。因此，如果您已登录 opencode go / zen（opencode auth login），则无需配置。deploy/env.example 仅包含非秘密设置；存储文件权限为 0600，位于 ~/.config 下，不在任何仓库中。

设置向导 + 探测（按需，非守护进程）

mcp-qmedia ui（= server.py ui [port]）在运行时提供 http://127.0.0.1:8938 服务——启动它，配置，关闭它（类似于 mcp-imap 的设置向导）：提供商列表（默认标记，密钥状态及来源——密钥本身从不发送到浏览器），添加/编辑/删除（内置提供商可重置，不可删除），设为默认，以及一个探测面板：粘贴 http(s) URL 或本地路径（每行一个），一个问题（空 = describe 提示），选择一个提供商，提问——答案 + 计时 + 每页历史记录。其后有 JSON API：GET/POST /api/providers，DELETE /api/providers/<name>，POST /api/default，POST /api/ask {files, question, provider}，以及 GET /api/status（CORS *，与消息传递守护进程的状态形状相同——中心页面（ai-agent-setup mcp-hub.service，http://127.0.0.1:8930/）会轮询它；字段集与守护进程相同——但 qmedia 不是守护进程，也没有中心卡片；它显示在中心的 Bridge 卡片中）。该页面链接到“所有守护进程 ↗”（http://127.0.0.1:8930/）；页面本身是 web/page.html。MCP 服务器在每次调用时读取相同的存储文件，因此更改立即生效，无需重启。

工具（在 opencode 中前缀为 qmedia_，在 Claude Code 中为 mcp__qmedia__）

• ask(files, question, backend="", system="")——主要工具。files 是绝对本地路径列表（~/… 可以；服务器是共享守护进程，其工作目录不是您的项目）或 http(s):// URL；一次调用中可包含多个文件，以便模型关联它们。返回一个简短头部（[mimo-v2.5 - opencode go/mimo-v2.5 · 2 个文件 · 8.8s] + 每个文件的类型/大小）和答案。

• describe(files, backend="")——无需问题：详细描述；图片包括所有可见文本逐字，音频为逐字转录，视频逐场景带时间戳和转录。

• backends()——提供商：端点、模型、哪个是默认、每个提供商是否有密钥解析（从不打印密钥）、ffmpeg 可用性、限制、存储路径。

权限：所有三个工具均为只读且廉价 → 在两个代理中均允许。注意：ask/describe 将给定的文件上传到配置的提供商（默认是付费 API）——允许列表通配符意味着代理可以在不询问的情况下执行此操作，包括计划模式；如果这对您很重要，请将默认值保留在免费提供商上。

媒体处理

类型检测：扩展名表 → mimetypes → HTTP Content-Type → 魔数。 ffmpeg 是可选的，但强烈推荐（dnf install ffmpeg）；没有它，只有不需要转码的文件才能工作。

2026-08-17 在 mimo-v2.5 - opencode go 上验证：图片 OCR，wav 转录（espeak 样本），3 秒 mp4 带哔哔声（帧 + 音轨），以及一次调用中的图片和音频。

设置

布局：server.py（stdio MCP 服务器 + ui 向导模式），web/page.html（向导页面），deploy/bin/mcp-qmedia（启动器），deploy/env.example（可选的非秘密设置）。没有 systemd 单元：在一台机器上有多个代理会话时，通过 mcp-proxy（ai-agent-setup 的 mcp-bridge.service）运行一次，或让每个客户端生成它。通过符号链接连接，以便 git pull 更新机器。

git clone git@github.com:spookysys/mcp-qmedia.git ~/.local/src/mcp-qmedia
cd ~/.local/src/mcp-qmedia
uv venv .venv --python 3.14 && uv pip install --python .venv/bin/python 'mcp>=1.9,<2' httpx
ln -s "$PWD/deploy/bin/mcp-qmedia" ~/.local/bin/          # launcher
# setup: mcp-qmedia ui   -> http://127.0.0.1:8938 (close it when done)
# optional: mkdir -p ~/.config/mcp-qmedia && cp deploy/env.example ~/.config/mcp-qmedia/env

opencode（opencode.jsonc）：

"qmedia": { "type": "local", "command": ["/home/YOU/.local/bin/mcp-qmedia"], "enabled": true }
// or, shared through mcp-bridge: { "type": "remote", "url": "http://127.0.0.1:8939/servers/qmedia/sse" }
// permission: "qmedia_*": "allow"

Claude Code（用户范围）：

claude mcp add -s user qmedia --transport stdio -- ~/.local/bin/mcp-qmedia
# or, shared through mcp-bridge: claude mcp add -s user qmedia --transport sse http://127.0.0.1:8939/servers/qmedia/sse
# settings.json permissions.allow: "mcp__qmedia__*"

环境变量