openmedia-mcp

컨텍스트 효율적인 MCP 서버 스위트로, 미디어 — 이미지, PDF, 비디오, 오디오 — 의 추출, 분석, 조작을 위해 설계되었으며 AI 에이전트를 대상으로 합니다.

stdio, streamable HTTP 또는 SSE를 통해 모든 MCP 호환 하네스(opencode, Claude Code/Desktop, Cursor, Windsurf, Cline, LM Studio, ...)와 함께 동작합니다.

왜?

멀티모달 모델은 볼 수는 있지만, 대부분의 하네스는 비디오, 스캔된 PDF 또는 20MB 사진을 실패 없이 또는 엄청난 컨텍스트를 소모하지 않고 확인할 수 있는 깔끔한 방법을 제공하지 않습니다. openmedia-mcp는 확실한 규칙을 적용해 이를 해결합니다.

• 모든 시각적 출력은 모델에 도달하기 전에 다운스케일 및 재압축됩니다 (최대 크기 / JPEG 품질을 설정할 수 있음).

• 모든 텍스트 출력은 상한이 있으며, 더 많은 내용을 가져오는 방법을 알려주는 명시적 절단 표시가 포함됩니다.

• 호출당 프레임/페이지 상한(12프레임, 8페이지)으로 의도치 않은 컨텍스트 홍수를 방지합니다.

• URL을 일급으로 지원합니다: 비디오 페이지 URL(YouTube + yt-dlp를 통한 1000개 이상 사이트)은 ≤720p로 한 번만 가져와 캐시되며, 직접적인 파일 URL은 크기 상한이 적용된 채 캐시됩니다.

Related MCP server: Vision MCP Server

요구 사항

Python ≥ 3.10과 시스템 바이너리가 필요합니다(모든 것은 호출 시점에 확인되며, 실제로 호출하는 도구에 해당하는 바이너리만 있으면 되는 실행 가능한 오류 메시지가 출력됩니다):

선택 사항: pip install 'openmedia-mcp[whisper]'를 실행하면 faster-whisper를 통해 로컬 음성-텍스트 변환(audio_transcribe)을 사용할 수 있습니다.

설치 및 실행

# From a local checkout
uv run --project /path/to/openmedia-mcp openmedia-mcp

# Or install as a tool
uv tool install git+https://github.com/Builderstar/openmedia-mcp.git
openmedia-mcp --tools pdf,image

opencode

{
  "mcp": {
    "openmedia": {
      "type": "local",
      "command": ["uv", "run", "--project", "/home/you/projects/openmedia-mcp", "openmedia-mcp"]
    }
  }
}

Claude Desktop / 일반 MCP 구성

{
  "mcpServers": {
    "openmedia": {
      "command": "uv",
      "args": ["run", "--project", "/home/you/projects/openmedia-mcp", "openmedia-mcp"]
    }
  }
}

HTTP 전송

openmedia-mcp --transport streamable-http --host 127.0.0.1 --port 8756

도구 세트

--tools image,pdf,video,audio(기본값: all)를 사용해 특정 하네스가 필요한 것만 마운트할 수 있습니다. media_probe는 항상 사용할 수 있습니다.

이미지

pdf

video

audio

설정 (환경 변수)

보안 및 개인정보

이 서버는 이 서버를 시작하는 사용자의 권한을 가지고 동작합니다. 이 서버의 도구는 로컬 미디어를 읽고, URL을 가져오고, 미디어 처리를 위한 바이너리를 실행하고, 호출자가 선택한 출력 경로로 쓸 수 있습니다. 도구 응답에는 절대 경로와 미디어 메타데이터가 포함될 수 있습니다. 신뢰할 수 있는 MCP 클라이언트만 연결하세요.

HTTP 전송 방식은 인증을 제공하지 않습니다. 자체 인증된 프록시와 네트워크 정책 없이는 기본적으로 반복 기준, 일반적으로 루프백에 바인딩됩니다. 다른 호스트 또는 신뢰할 수 없는 네트워크에 노출하지 마세요. URL 가져오기는 호스트에서 볼 수 있는 주소(사설 네트워크 서비스 포함)에 도달할 수 있습니다.

선택 사양의 Whisper 도구는 도구가 처음 실행될 때 base faster-whisper 모델을 다운로드하여 캐시합니다. 오프라인 사용을 위해 해당 모델 캐시를 사전에 준비하세요.

Development

uv sync                          # install deps
uv run python tests/smoke_test.py [sample-video.mp4]   # exercises every tool

스모크 테스트는 자체 테스트 이미지나 PDF를 생성합니다. 비디오/오디오 도구 모음도 함께 테스트하려면 로컬 비디오 파일을 전달하세요.

라이선스

MIT