mcp-qmedia

직접 작성한 MCP 서버로, 텍스트 전용 에이전트가 미디어에 대해 질문할 수 있게 해줍니다 — 이미지, 오디오, 비디오. 에이전트가 파일 경로(또는 URL)와 질문을 전달하면, 서버가 이를 Xiaomi MiMo-V2.5(기본적으로 전방향 모달: 텍스트/이미지/오디오/비디오 입력, 텍스트 출력)로 OpenCode Zen 엔드포인트를 통해 전송하고 답변을 텍스트로 반환합니다. opencode와 Claude Code에서 모두 사용됩니다.

제공자

모든 제공자에 대해 동일한 코드 경로(OpenAI 호환 /chat/completions, base64 콘텐츠 파트)를 사용합니다. 두 가지가 내장되어 있으며, 웹 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 file(s) · 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__*"

환경 변수