Skip to main content
Glama

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

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

Available Tools

22 tools
audio_convertA

Convert an audio file to another format, optionally changing bitrate, sample rate, or downmixing to mono.

Args: source: Local file path or direct URL to an audio file. output_format: mp3, m4a, wav, flac, opus, or ogg (default mp3). output_path: Target path. Defaults to ~/Downloads/openmedia/. bitrate: e.g. '128k', '192k' (lossy formats only). sample_rate: e.g. 16000, 44100 (0 = keep). 16000 mono is ideal for speech-to-text pipelines. mono: Downmix to a single channel.

Inputs: source (required), mono, bitrate, output_path, +2 more. Returns: result

audio_infoA

Get audio file metadata: codec, duration, sample rate, channels, bitrate, and embedded tags (title, artist, album, etc.).

Args: source: Local file path or direct http(s) URL to an audio file.

Inputs: source (required). Returns: result

audio_transcribeA

Transcribe speech in an audio file to text using a local Whisper model (faster-whisper). Requires the optional dependency: uv pip install 'openmedia-mcp[whisper]' or pip install faster-whisper.

Args: source: Local file path or direct URL to an audio file. language: Language hint like 'en', 'de' (empty = auto-detect). max_chars: Character cap (0 = default cap).

Inputs: source (required), language, max_chars. Returns: result

audio_trimA

Cut a section out of an audio file into a new file (stream copy, lossless).

Args: source: Local file path or direct URL to an audio file. start: Start time (seconds or MM:SS / HH:MM:SS). end: End time. output_path: Target path. Defaults to ~/Downloads/openmedia/.

Inputs: end (required), start (required), source (required), output_path. Returns: result

audio_waveformA

Render the audio waveform as an image the model can see. Useful for spotting silence, clipping, loudness structure, speech vs music sections.

Args: source: Local file path or direct URL to an audio file. width: Image width in px (default 1024). height: Image height in px (default 256). split_channels: Draw each channel separately.

Inputs: source (required), width, height, split_channels.

image_compareA

View two images side by side in a single composite for visual comparison.

Args: source_a: First image (path or URL). source_b: Second image (path or URL). max_dimension: Longest edge of the combined composite (default 768).

Inputs: source_a (required), source_b (required), max_dimension.

image_infoA

Get image metadata without viewing it: format, dimensions, mode, file size, and a summary of relevant EXIF fields (camera, timestamps, orientation, GPS presence).

Args: source: Local file path or direct http(s) URL to an image.

Inputs: source (required). Returns: result

image_ocrA

Extract text from an image using Tesseract OCR.

Args: source: Local file path or direct http(s) URL to an image. language: Tesseract language code(s), e.g. 'eng', 'deu', 'eng+deu'. max_chars: Character cap for the result (0 = default cap).

Inputs: source (required), language, max_chars. Returns: result

image_transformA

Transform an image: crop, resize, rotate, flip, grayscale, and/or convert format.

Operations apply in order: crop -> resize -> rotate -> flip -> grayscale. Only the operations you specify are applied. The result is written to disk.

Args: source: Local file path or direct http(s) URL to an image. output_path: Where to save. Defaults to ~/Downloads/openmedia/. resize_width: Target width in px (0 = derive from height, keep aspect). resize_height: Target height in px (0 = derive from width, keep aspect). crop: "x,y,width,height" crop box in pixels. rotate: Degrees counter-clockwise (expands canvas). flip: "horizontal" or "vertical". grayscale: Convert to grayscale. output_format: Target format: png, jpeg, webp, bmp, tiff, gif (default: keep). quality: Quality for lossy formats (default 90). return_preview: Also return a small preview of the result to the model.

Inputs: source (required), crop, flip, rotate, +7 more.

image_viewA

View an image (local path or URL) as model-visible content.

The image is automatically downscaled and recompressed to protect context. Use region ("x,y,width,height" in original pixel coordinates) to zoom into a detail at full resolution instead of viewing the whole image.

Args: source: Local file path or direct http(s) URL to an image. max_dimension: Longest edge of the returned image (64-4096, default 1024). quality: JPEG quality 20-95 (default 80). region: Optional crop "x,y,w,h" applied before scaling, for zooming in.

Inputs: source (required), region, quality, max_dimension.

media_probeA

Identify what kind of media a file or URL is and which tools apply. Use this first when the media type is unknown.

Args: source: Local file path or URL.

Inputs: source (required). Returns: result

pdf_extract_imagesA

Extract embedded raster images (figures, photos) from a PDF to files on disk. Returns the file list; use image_view afterwards to look at specific ones.

Args: source: Local file path or direct http(s) URL to a PDF. pages: Page selection like '1-5'. Empty = whole document. output_dir: Directory for extracted images. Defaults to ~/Downloads/openmedia/. min_dimension: Skip images smaller than this in both dimensions (filters icons/bullets, default 64).

Inputs: source (required), pages, output_dir, min_dimension. Returns: result

pdf_infoA

Get PDF metadata: page count, title, author, dates, encryption, page size, file size, and whether the PDF has an embedded text layer (vs scanned-only).

Use this first to decide between pdf_read (text layer) and pdf_view/pdf_ocr (scanned).

Args: source: Local file path or direct http(s) URL to a PDF.

Inputs: source (required). Returns: result

pdf_ocrA

OCR scanned PDF pages into text using Tesseract. Slower than pdf_read but works on PDFs without a text layer. Capped at 10 pages per call.

Args: source: Local file path or direct http(s) URL to a PDF. pages: Page selection like '1-5'. Default first page. language: Tesseract language code(s), e.g. 'eng', 'eng+deu'. dpi: Render resolution before OCR (150-300, default 200). max_chars: Character cap for the result (0 = default cap).

Inputs: source (required), dpi, pages, language, +1 more. Returns: result

pdf_readA

Extract text from a PDF's text layer. Fast and cheap; use for born-digital PDFs.

For scanned PDFs (no text layer, check with pdf_info) use pdf_ocr or pdf_view.

Args: source: Local file path or direct http(s) URL to a PDF. pages: Page selection like '1-5' or '2,4,9-12'. Empty = whole document. max_chars: Character cap for the result (0 = default cap of 20000). preserve_layout: Keep original physical layout (tables/columns line up).

Inputs: source (required), pages, max_chars, preserve_layout. Returns: result

pdf_viewA

Render PDF pages as images the model can see. Use for scanned documents, figures, charts, complex layouts, or to verify visual appearance.

Capped at 8 pages per call to protect context; request ranges in batches.

Args: source: Local file path or direct http(s) URL to a PDF. pages: Page selection like '1', '1-4', '2,5,8'. Default first page. dpi: Render resolution (72-300, default 120; raise for small print). max_dimension: Longest edge of each returned image (default 1024). quality: JPEG quality 20-95 (default 80).

Inputs: source (required), dpi, pages, quality, +1 more.

video_clipA

Cut a section out of a video into a new file.

Args: source: Local file path or video URL (URLs fetched at <=720p first). start: Clip start (seconds or HH:MM:SS). end: Clip end (seconds or HH:MM:SS). output_path: Target path. Defaults to ~/Downloads/openmedia/. reencode: Re-encode for frame-exact cuts (slower). Default is stream copy, which is instant but snaps to keyframes.

Inputs: end (required), start (required), source (required), reencode, +1 more. Returns: result

video_downloadA

Download a video (or just its audio) from a URL to disk via yt-dlp. Supports YouTube and 1000+ other sites. Returns the saved file path.

Args: source: Video page URL. resolution: '480p', '720p', '1080p', or 'best'. audio_only: Download best audio only (m4a/opus). output_path: Target file path. Defaults to ~/Downloads/openmedia/.

Inputs: source (required), audio_only, resolution, output_path. Returns: result

video_extract_audioA

Extract the audio track from a video into an audio file.

Args: source: Local file path or video URL. output_format: mp3, m4a, wav, flac, or opus (default mp3). output_path: Target path. Defaults to ~/Downloads/openmedia/. start: Optional start time to extract only a section. end: Optional end time.

Inputs: source (required), end, start, output_path, +1 more. Returns: result

video_framesA

Extract frames from a video and return them as model-visible images. This is how you SEE a video's content. Works on local files and URLs (remote videos are fetched once at <=720p and cached).

Either pass explicit timestamps, or let count frames be sampled uniformly across the duration (optionally restricted to a start/end window). Capped at 12 frames per call; make additional calls for more coverage.

Args: source: Local file path or video page URL. timestamps: Comma-separated explicit times, e.g. '0:05, 1:30, 95.5'. count: Number of uniformly spaced frames when timestamps not given (1-12). start: Optional window start for uniform sampling (seconds or MM:SS). end: Optional window end for uniform sampling. max_dimension: Longest edge of each frame (default 768). quality: JPEG quality (default 75).

Inputs: source (required), end, count, start, +3 more.

video_infoA

Get video metadata. For local files: container, duration, streams, codecs, resolution, fps, chapters. For URLs (YouTube and 1000+ sites): title, channel, duration, views, upload date, available subtitles - without downloading.

Args: source: Local file path or a video page URL (YouTube, Vimeo, etc.).

Inputs: source (required). Returns: result

video_transcriptA

Get a clean text transcript of a video. For URLs, fetches manual subtitles or auto-captions via yt-dlp (no video download). For local files, extracts an embedded subtitle track if present.

Args: source: Local file path or video page URL. language: Subtitle language code (e.g. 'en', 'de', 'ja'). include_timestamps: Prefix lines with [MM:SS] markers. max_chars: Character cap (0 = default cap of 20000).

Inputs: source (required), language, max_chars, include_timestamps. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 22 tools

    Disambiguation5/5

    Each tool targets a distinct media type and action, with clear boundaries (e.g., pdf_read vs pdf_ocr vs pdf_view explicitly address text layer vs scanned). The media_probe helper reduces ambiguity by routing to the correct tools. No two tools appear to do the same thing.

    Naming Consistency5/5

    All tools follow a strict pattern: media type prefix (image_, pdf_, video_, audio_) followed by a descriptive verb (view, info, transform, read, convert, clip). All snake_case, no mixed conventions, and the pattern makes tool purposes predictable.

    Tool Count4/5

    22 tools is on the heavy side, but the server covers four distinct media domains (image, PDF, video, audio) each with a logical set of operations. Every tool earns its place given the broad scope, though it slightly exceeds the typical comfortable range.

    Completeness5/5

    The surface covers the full lifecycle for each media type: inspection (info/probe), viewing/reading, transformation/conversion, extraction (OCR, transcript, frames, audio), and editing (clip, trim). No obvious dead ends or critical missing operations for the stated purpose.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers