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.

Related MCP server: Vision MCP Server

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

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

pdf

video

audio

Configuration (env vars)

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