mcp-qmedia

Servidor MCP propio que permite a agentes solo de texto hacer preguntas sobre contenido multimedia — imágenes, audio, video. El agente pasa rutas de archivo (o URLs) junto con una pregunta; el servidor las envía a Xiaomi MiMo-V2.5 (nativamente omni-modal: texto/imagen/audio/video de entrada, texto de salida) a través de los endpoints OpenCode Zen y devuelve la respuesta como texto. Se utiliza tanto desde opencode como desde Claude Code.

Proveedores

Mismo código para todos (compatible con OpenAI /chat/completions, partes de contenido en base64). Hay dos integrados; se pueden añadir más, eliminar y cambiar el predeterminado en la interfaz web (abajo) — o editando el almacén ~/.config/mcp-qmedia/providers.json (0600, fuera del repositorio; puede contener claves). Por llamada: backend="<nombre>"; QMEDIA_BACKEND anula el valor predeterminado almacenado.

Related MCP server: Vision MCP Server

Claves API — nunca en este repositorio

Por proveedor, orden de resolución: la clave propia del proveedor en el almacén (establecida a través de la interfaz) → QMEDIA_API_KEY → OPENCODE_API_KEY → ~/.local/share/opencode/auth.json (QMEDIA_AUTH_JSON): la auth_entry del proveedor, luego cualquier otra entrada con una clave. Por lo tanto, si has iniciado sesión en opencode go / zen (opencode auth login), no hay nada que configurar. deploy/env.example solo contiene ajustes no secretos; el almacén se escribe con permisos 0600 y reside en ~/.config, no en ningún repositorio.

Asistente de configuración + prueba (bajo demanda, no un daemon)

mcp-qmedia ui (= server.py ui [port]) sirve http://127.0.0.1:8938 mientras se ejecuta — inícialo, configúralo, ciérralo (como el asistente de configuración de mcp-imap): lista de proveedores (predeterminado marcado, estado de la clave + de dónde proviene — la clave en sí nunca se envía al navegador), añadir/editar/eliminar (los integrados se pueden restablecer, no eliminar), establecer como predeterminado, y un panel de prueba: pega URLs http(s) o rutas locales (una por línea), una pregunta (vacía = el prompt describe), elige un proveedor, Preguntar — respuesta + tiempo + historial por página. API JSON detrás: GET/POST /api/providers, DELETE /api/providers/<nombre>, POST /api/default, POST /api/ask {files, question, provider}, y GET /api/status (CORS *, misma forma que el estado de los daemons de mensajería — la página central (ai-agent-setup mcp-hub.service, http://127.0.0.1:8930/) la consulta; el mismo conjunto de campos que los daemons — pero qmedia no es un daemon y no tiene tarjeta de hub; aparece en la tarjeta Bridge del hub). La página enlaza a "Todos los daemons ↗" (http://127.0.0.1:8930/); la página en sí es web/page.html. El servidor MCP lee el mismo almacén en cada llamada, por lo que los cambios se aplican inmediatamente sin necesidad de reiniciar.

Herramientas (prefijo qmedia_ en opencode, mcp__qmedia__ en Claude Code)

• ask(files, question, backend="", system="") — la herramienta principal. files es una lista de rutas locales absolutas (~/… está bien; el servidor es un daemon compartido, su directorio de trabajo no es tu proyecto) o URLs http(s)://; varios archivos en una sola llamada para que el modelo pueda relacionarlos. Devuelve un encabezado corto ([mimo-v2.5 - opencode go/mimo-v2.5 · 2 archivo(s) · 8.8s] + tipo/tamaño por archivo) y la respuesta.

• describe(files, backend="") — no se necesita pregunta: descripción exhaustiva; imágenes incluyendo todo el texto visible textualmente, audio como transcripción textual, video escena por escena con marcas de tiempo + transcripción.

• backends() — proveedores: endpoints, modelos, cuál es el predeterminado, si se resuelve una clave para cada uno (nunca imprime la clave), disponibilidad de ffmpeg, límites, ruta del almacén.

Permiso: las tres son de solo lectura y económicas → permitir en ambos agentes. Nota: ask/describe suben los archivos dados al proveedor configurado (una API de pago para el predeterminado) — un comodín de lista de permitidos significa que un agente puede hacerlo sin preguntar, incluido el modo de plan; mantén el predeterminado en el proveedor gratuito si eso te importa.

Manejo de medios

Detección de tipo: tabla de extensiones → mimetypes → Content-Type HTTP → bytes mágicos. ffmpeg es opcional pero muy recomendado (dnf install ffmpeg); sin él, solo funcionan los archivos que no necesitan transcodificación.

Verificado el 2026-08-17 en mimo-v2.5 - opencode go: OCR de imágenes, transcripción wav (muestra de espeak), mp4 de 3 s con pitido (fotogramas + banda sonora), e imagen+audio en una sola llamada.

Configuración

Estructura: server.py (servidor MCP stdio + modo asistente ui), web/page.html (la página del asistente), deploy/bin/mcp-qmedia (lanzador), deploy/env.example (ajustes no secretos opcionales). Sin unidad systemd: en una máquina con varias sesiones de agente, ejecútalo una vez a través de mcp-proxy (mcp-bridge.service de ai-agent-setup) o deja que cada cliente lo inicie. Conéctalo con enlaces simbólicos para que un git pull actualice la máquina.

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 (ámbito de usuario):

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__*"

Variables de entorno