mcp-qmedia

Eigenentwickelter MCP-Server, der es textbasierten Agenten ermöglicht, Fragen zu Medien zu stellen – Bilder, Audio, Video. Der Agent übergibt Dateipfade (oder URLs) plus eine Frage; der Server sendet sie an Xiaomi MiMo-V2.5 (nativ omni-modal: Text/Bild/Audio/Video rein, Text raus) über die OpenCode Zen-Endpunkte und gibt die Antwort als Text zurück. Wird sowohl von opencode als auch von Claude Code verwendet.

Anbieter

Gleicher Codepfad für alle (OpenAI-kompatible /chat/completions, Base64-Inhaltsteile). Zwei sind integriert; weitere können über die Web-Oberfläche (unten) hinzugefügt, entfernt und der Standard gewechselt werden – oder durch Bearbeiten des Stores ~/.config/mcp-qmedia/providers.json (0600, außerhalb des Repos; kann Schlüssel enthalten). Pro Aufruf: backend="<name>"; QMEDIA_BACKEND überschreibt den gespeicherten Standard.

Related MCP server: Vision MCP Server

API-Schlüssel – niemals in diesem Repository

Pro Anbieter, Auflösungsreihenfolge: der eigene Schlüssel des Anbieters im Store (über die UI gesetzt) → QMEDIA_API_KEY → OPENCODE_API_KEY → ~/.local/share/opencode/auth.json (QMEDIA_AUTH_JSON): der auth_entry des Anbieters, dann jeder andere Eintrag mit einem Schlüssel. Wenn Sie also bei opencode go / zen angemeldet sind (opencode auth login), ist nichts zu konfigurieren. deploy/env.example enthält nur nicht-geheime Einstellungen; der Store wird mit 0600 geschrieben und liegt unter ~/.config, nicht in einem Repository.

Einrichtungsassistent + Test (auf Abruf, kein Dienst)

mcp-qmedia ui (= server.py ui [port]) bedient http://127.0.0.1:8938, solange es läuft – starten, konfigurieren, schließen (wie mcp-imaps Einrichtungsassistent): Liste der Anbieter (Standard markiert, Schlüsselstatus + woher der Schlüssel kommt – der Schlüssel selbst wird nie an den Browser gesendet), hinzufügen/bearbeiten/entfernen (eingebaute können zurückgesetzt, nicht entfernt werden), Standard festlegen, und ein Test-Panel: HTTP(s)-URLs oder lokale Pfade einfügen (eine pro Zeile), eine Frage (leer = die describe-Aufforderung), einen Anbieter auswählen, Fragen – Antwort + Zeit + seitenweise Verlauf. JSON-API dahinter: GET/POST /api/providers, DELETE /api/providers/<name>, POST /api/default, POST /api/ask {files, question, provider}, und GET /api/status (CORS *, gleiche Form wie der Status der Nachrichtendienste – die Hub-Seite (ai-agent-setup mcp-hub.service, http://127.0.0.1:8930/) fragt sie ab; eine gleiche Feldermenge wie die Dienste – aber qmedia ist kein Dienst und hat keine Hub-Karte; es erscheint in der Bridge-Karte des Hubs). Die Seite verlinkt zu "Alle Dienste ↗" (http://127.0.0.1:8930/); die Seite selbst ist web/page.html. Der MCP-Server liest bei jedem Aufruf denselben Store, sodass Änderungen sofort ohne Neustart wirksam werden.

Werkzeuge (Präfix qmedia_ in opencode, mcp__qmedia__ in Claude Code)

• ask(files, question, backend="", system="") – das Hauptwerkzeug. files ist eine Liste von absoluten lokalen Pfaden (~/… ist okay; der Server ist ein gemeinsamer Dienst, sein Arbeitsverzeichnis ist nicht Ihr Projekt) oder http(s):// URLs; mehrere Dateien in einem Aufruf, damit das Modell sie in Beziehung setzen kann. Gibt einen kurzen Header zurück ([mimo-v2.5 - opencode go/mimo-v2.5 · 2 Datei(en) · 8,8 s] + pro Datei Typ/Größe) und die Antwort.

• describe(files, backend="") – keine Frage nötig: ausführliche Beschreibung; Bilder inkl. aller sichtbaren Texte wörtlich, Audio als wörtliches Transkript, Video Szene für Szene mit Zeitstempeln + Transkript.

• backends() – Anbieter: Endpunkte, Modelle, welcher Standard ist, ob ein Schlüssel für jeden aufgelöst wird (gibt nie den Schlüssel aus), ffmpeg-Verfügbarkeit, Grenzen, Store-Pfad.

Berechtigung: Alle drei sind schreibgeschützt und günstig → erlauben in beiden Agenten. Hinweis: ask/describe laden die angegebenen Dateien auf den konfigurierten Anbieter hoch (eine kostenpflichtige API für den Standard) – ein Erlaubnis-Wildcard bedeutet, dass ein Agent dies ohne Nachfrage tun kann, inklusive Plan-Modus; behalten Sie den Standard auf dem kostenlosen Anbieter, falls Ihnen das wichtig ist.

Medienverarbeitung

Typ-Erkennung: Erweiterungstabelle → mimetypes → HTTP Content-Type → Magic-Bytes. ffmpeg ist optional, aber dringend empfohlen (dnf install ffmpeg); ohne es funktionieren nur Dateien, die keine Transcodierung benötigen.

Getestet am 17.08.2026 auf mimo-v2.5 - opencode go: Bild-OCR, wav-Transkription (espeak-Beispiel), 3 s mp4 mit Piepton (Frames + Tonspur) und Bild+Audio in einem Aufruf.

Einrichtung

Aufbau: server.py (stdio MCP-Server + ui-Assistentenmodus), web/page.html (die Assistentenseite), deploy/bin/mcp-qmedia (Starter), deploy/env.example (optionale nicht-geheime Einstellungen). Kein systemd-Unit: auf einem Rechner mit mehreren Agentensitzungen, starten Sie es einmal über mcp-proxy (ai-agent-setups mcp-bridge.service) oder lassen Sie jeden Client es starten. Einbinden mit Symlinks, sodass ein git pull den Rechner aktualisiert.

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 (Benutzerkontext):

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

Umgebungsvariablen