openmedia-mcp

Context-efficient MCP server suite for extracting, analyzing and manipulating media — images, PDFs, video, audio — designed for AI agents.

Works with any MCP-compatible harness (opencode, Claude Code/Desktop, Cursor, Windsurf, Cline, LM Studio, ...) over stdio, streamable HTTP, or SSE.

Why

Multimodal models can see, but most harnesses give them no clean way to look at a video, a scanned PDF, or a 20 MB photo without either failing or burning enormous context. openmedia-mcp fixes that with hard rules:

• Every visual output is downscaled + recompressed before it reaches the model (configurable max dimension / JPEG quality).
• Every text output is capped with an explicit truncation marker telling the model how to fetch more.
• Frame/page caps per call (12 frames, 8 pages) prevent accidental context floods.
• URLs are first-class: video page URLs (YouTube + 1000+ sites via yt-dlp) are fetched once at ≤720p and cached; direct file URLs are cached with a size cap.

Requirements

Python ≥ 3.10 plus system binaries (all resolved at call time with actionable error messages — only the tools you actually call need their binary):

Binary	Needed for	Arch package
ffmpeg/ffprobe	video, audio	ffmpeg
yt-dlp	video URLs, downloads	yt-dlp
pdftotext/pdftoppm/pdfinfo/pdfimages	pdf	poppler
tesseract	image_ocr, pdf_ocr	tesseract + language data

Optional: pip install 'openmedia-mcp[whisper]' enables local speech-to-text (audio_transcribe) via faster-whisper.

Install & run

# 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 / generic MCP config

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

HTTP transport

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

Toolsets

Mount only what a given harness needs with --tools image,pdf,video,audio (default: all). media_probe is always available.

image

Tool	Purpose
image_view	See an image (auto-downscaled); region param zooms into details
image_info	Format, dimensions, EXIF summary — no pixels spent
image_ocr	Tesseract text extraction
image_transform	crop / resize / rotate / flip / grayscale / format convert
image_compare	Two images side-by-side in one composite

pdf

Tool	Purpose
pdf_info	Metadata + detects whether a text layer exists
pdf_read	Text-layer extraction (page ranges, layout mode)
pdf_view	Render pages as images for the model (scans, figures, layout)
pdf_ocr	Tesseract OCR for scanned PDFs
pdf_extract_images	Pull embedded figures/photos to disk

video

Tool	Purpose
video_info	ffprobe for files; yt-dlp metadata for URLs (no download)
video_frames	See the video: uniform sampling or exact timestamps
video_transcript	Captions via yt-dlp (URLs) or embedded subs (files)
video_download	yt-dlp download with resolution control
video_clip	Cut sections (stream-copy or re-encode)
video_extract_audio	Audio track to mp3/m4a/wav/flac/opus

audio

Tool	Purpose
audio_info	Codec, duration, tags
audio_convert	Format/bitrate/sample-rate/mono conversion
audio_trim	Lossless section cut
audio_waveform	See the waveform as an image
audio_transcribe	Local Whisper STT (optional [whisper] extra)

Configuration (env vars)

Variable	Default	Meaning
OPENMEDIA_CACHE_DIR	~/.cache/openmedia-mcp	URL/video download cache
OPENMEDIA_OUTPUT_DIR	~/Downloads/openmedia	Default output location
OPENMEDIA_TEXT_CAP	20000	Default max chars for text outputs
OPENMEDIA_MAX_IMAGE_DIM	1024	Default longest edge for returned images
OPENMEDIA_JPEG_QUALITY	80	Default JPEG quality
OPENMEDIA_MAX_DOWNLOAD_BYTES	209715200	Direct-URL download cap

Security and privacy

This server acts with the permissions of the user who starts it. Its tools can read local media, fetch URLs, run media-processing binaries, and write to caller-selected output paths. Tool responses may include absolute paths and media metadata. Only connect trusted MCP clients.

The HTTP transports do not provide authentication. They bind to loopback by default; do not expose them to another host or an untrusted network without a separate authenticated proxy and network policy. URL fetching can reach addresses visible from the host, including private-network services.

The optional Whisper tool downloads and caches the base faster-whisper model on first use. Prepare that model cache in advance for offline operation.

Development

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

The smoke test generates its own test image and PDF; pass any local video file to also cover the video/audio toolsets.

License

MIT