openmedia-mcp
Provides tools for working with YouTube videos, including metadata inspection, frame extraction, transcript/caption retrieval, and downloading video from YouTube URLs with resolution control and caching.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@openmedia-mcp Pull the first page of this PDF as an image and describe the layout"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| video, audio |
|
| video URLs, downloads |
|
|
| |
| image_ocr, pdf_ocr |
|
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,imageopencode
{
"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 8756Toolsets
Mount only what a given harness needs with --tools image,pdf,video,audio
(default: all). media_probe is always available.
image
Tool | Purpose |
| See an image (auto-downscaled); |
| Format, dimensions, EXIF summary — no pixels spent |
| Tesseract text extraction |
| crop / resize / rotate / flip / grayscale / format convert |
| Two images side-by-side in one composite |
Tool | Purpose |
| Metadata + detects whether a text layer exists |
| Text-layer extraction (page ranges, layout mode) |
| Render pages as images for the model (scans, figures, layout) |
| Tesseract OCR for scanned PDFs |
| Pull embedded figures/photos to disk |
video
Tool | Purpose |
| ffprobe for files; yt-dlp metadata for URLs (no download) |
| See the video: uniform sampling or exact timestamps |
| Captions via yt-dlp (URLs) or embedded subs (files) |
| yt-dlp download with resolution control |
| Cut sections (stream-copy or re-encode) |
| Audio track to mp3/m4a/wav/flac/opus |
audio
Tool | Purpose |
| Codec, duration, tags |
| Format/bitrate/sample-rate/mono conversion |
| Lossless section cut |
| See the waveform as an image |
| Local Whisper STT (optional |
Configuration (env vars)
Variable | Default | Meaning |
|
| URL/video download cache |
|
| Default output location |
|
| Default max chars for text outputs |
|
| Default longest edge for returned images |
|
| Default JPEG quality |
|
| 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 toolThe 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 toolsaudio_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
Scored across 22 tools
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.
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.
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.
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
Related MCP Connectors
Video, audio, and image processing for AI agents: convert, transcribe, upscale - 150+ operations.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Image & PDF tools for AI agents: compress, convert, resize, PDF, AI vision, pipeline.
PDF, image, video, OCR, screenshot, SQL, QR and text tools for agents. No API key, no signup.
Related MCP Servers
- FlicenseNot gradedqualityBmaintenanceEnables AI agents to process files locally — OCR images, extract text from PDFs and DOCX, and describe images using local vision models, all without sending data to external services.-
- AlicenseAqualityDmaintenanceEnables AI agents to analyze images, extract text, compare images, and analyze video through any OpenAI-compatible vision model.4330 npm20MIT
- FlicenseNot gradedqualityBmaintenanceEnables text-only AI agents to ask questions about images, audio, and video by passing file paths or URLs to a multimodal model and returning text answers.-
- AlicenseNot gradedqualityBmaintenanceProvides local, offline transcription, keyframe extraction, OCR, and pre-publish review of audio, video, and image files, enabling AI agents to see and hear media without cloud or API keys.55 npmApache 2.0