mcp-qmedia

テキストのみのエージェントがメディア（画像、音声、動画）について質問できるようにする自作のMCPサーバー。エージェントはファイルパス（またはURL）と質問を渡し、サーバーはそれらをOpenCode Zenエンドポイント経由でXiaomi MiMo-V2.5（ネイティブに全モーダル：テキスト/画像/音声/動画入力、テキスト出力）に送信し、回答をテキストで返します。opencodeとClaude Codeの両方から使用されます。

プロバイダー

すべて同じコードパス（OpenAI互換の/chat/completions、base64コンテンツパーツ）。2つが組み込まれており、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またはローカルパスを貼り付け（1行に1つ）、質問（空の場合は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は絶対パスのローカルパス（~/…も可。サーバーは共有デーモンであり、そのcwdはプロジェクトではありません）またはhttp(s):// URLのリスト。1回の呼び出しで複数のファイルを指定できるため、モデルはそれらを関連付けることができます。短いヘッダー（[mimo-v2.5 - opencode go/mimo-v2.5 · 2 file(s) · 8.8s] + ファイルごとのタイプ/サイズ）と回答を返します。

• describe(files, backend="") — 質問は不要：詳細な説明。画像はすべての可視テキストをそのまま含み、音声はそのままの文字起こし、動画はタイムスタンプと文字起こし付きのシーンごとの説明。

• backends() — プロバイダー：エンドポイント、モデル、デフォルト、各プロバイダーにキーが解決するかどうか（キーは決して表示しない）、ffmpegの可用性、制限、ストアパス。

権限：3つすべて読み取り専用で低コスト → 両方のエージェントで許可。注意：ask/describeは指定されたファイルを設定されたプロバイダー（デフォルトは有料API）にアップロードします — ワイルドカードの許可リストは、エージェントが許可なくそれを行うことができることを意味します（プランモードも含む）。それが気になる場合は、デフォルトを無料プロバイダーにしておいてください。

メディア処理

タイプ検出：拡張子テーブル → mimetypes → HTTP Content-Type → マジックバイト。 ffmpegはオプションですが強く推奨します（dnf install ffmpeg）。ffmpegがない場合、トランスコード不要のファイルのみが機能します。

2026-08-17にmimo-v2.5 - opencode goで確認済み：画像OCR、wav文字起こし（espeakサンプル）、3秒のmp4ビープ音（フレーム+サウンドトラック）、および1回の呼び出しでの画像+音声。

セットアップ

レイアウト：server.py（stdio MCPサーバー + uiウィザードモード）、web/page.html（ウィザードページ）、deploy/bin/mcp-qmedia（ランチャー）、deploy/env.example（オプションの非秘密設定）。systemdユニットなし：複数のエージェントセッションがある1台のマシンでは、mcp-proxy（ai-agent-setupのmcp-bridge.service）を介して1回実行するか、各クライアントに起動させます。シンボリックリンクで配線すると、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__*"

環境変数