{ "markdown": "

\n \"media-context-mcp\n

\n\n

\n \"npm\n \"npm\n \"license\"\n \"node\"\n

\n\n

\n Give your AI assistant eyes and ears.
\n Analyze any video, audio, or image — locally, right inside your editor.\n

\n\n

\n Install  · \n Capabilities  · \n Modes  · \n Examples  · \n Tools  · \n Options  · \n Docs\n

\n\n
\n\nLLMs read text and glance at a single image — but they can't watch a video or listen to audio. **media-context-mcp** closes that gap. Hand it a file or a link and it returns clean, model-ready context — keyframes, a transcript, or the text on screen — entirely on your machine. Nothing is uploaded.\n\n

\n \"A\n

\n\n

A 10-second clip becomes one tidy contact sheet your model reads in order — not hundreds of stills.

\n\n
\n\n## 🚀 Install\n\nTwo steps — add the server, then install the local helpers it uses.\n\n### 1 · Add the server to your client\n\n```bash\n# Claude Code\nclaude mcp add media-context -- npx -y media-context-mcp\n```\n\nThe launch command is always `npx -y media-context-mcp`. Pick your client:\n\n
\nClaude Desktop\n\nSettings → Developer → Edit Config (`claude_desktop_config.json`):\n\n```json\n{\n \"mcpServers\": {\n \"media-context\": { \"command\": \"npx\", \"args\": [\"-y\", \"media-context-mcp\"] }\n }\n}\n```\n
\n\n
\nCursor\n\n`~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project):\n\n```json\n{\n \"mcpServers\": {\n \"media-context\": { \"command\": \"npx\", \"args\": [\"-y\", \"media-context-mcp\"] }\n }\n}\n```\n
\n\n
\nVS Code (GitHub Copilot, agent mode)\n\n`.vscode/mcp.json` — VS Code uses the `servers` key:\n\n```json\n{\n \"servers\": {\n \"media-context\": { \"command\": \"npx\", \"args\": [\"-y\", \"media-context-mcp\"] }\n }\n}\n```\n
\n\n
\nWindsurf\n\n`~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"media-context\": { \"command\": \"npx\", \"args\": [\"-y\", \"media-context-mcp\"] }\n }\n}\n```\n
\n\n
\nCline / Roo Code\n\n`cline_mcp_settings.json` (the extension's MCP settings):\n\n```json\n{\n \"mcpServers\": {\n \"media-context\": { \"command\": \"npx\", \"args\": [\"-y\", \"media-context-mcp\"] }\n }\n}\n```\n
\n\n
\nKiro\n\n`.kiro/settings/mcp.json` (project) or `~/.kiro/settings/mcp.json` (user):\n\n```json\n{\n \"mcpServers\": {\n \"media-context\": { \"command\": \"npx\", \"args\": [\"-y\", \"media-context-mcp\"] }\n }\n}\n```\n
\n\n
\nGemini CLI\n\n`~/.gemini/settings.json`:\n\n```json\n{\n \"mcpServers\": {\n \"media-context\": { \"command\": \"npx\", \"args\": [\"-y\", \"media-context-mcp\"] }\n }\n}\n```\n
\n\n
\nZed\n\n`settings.json` — Zed uses `context_servers`:\n\n```json\n{\n \"context_servers\": {\n \"media-context\": { \"command\": { \"path\": \"npx\", \"args\": [\"-y\", \"media-context-mcp\"] } }\n }\n}\n```\n
\n\n
\nCodex CLI\n\n`~/.codex/config.toml`:\n\n```toml\n[mcp_servers.media-context]\ncommand = \"npx\"\nargs = [\"-y\", \"media-context-mcp\"]\n```\n
\n\n
\nJetBrains AI Assistant\n\nSettings → Tools → AI Assistant → Model Context Protocol → Add, then use command `npx` with args `-y media-context-mcp`.\n
\n\n> **Tip:** in Claude Code you can install it as a plugin instead — run `/plugin marketplace add vishalguptax/media-context-mcp`, then `/plugin install media-context`. To share with a team, install per-project: `--scope project` (writes `.mcp.json`) or commit a `.cursor/mcp.json` in the repo.\n\n### 2 · Install the local helpers\n\nOne command sets up everything the server uses, via your OS package manager:\n\n```bash\nnpx media-context-mcp setup # core: keyframes, links, on-screen text\nnpx media-context-mcp setup --audio # also enable transcription\n```\n\nThe server finds the helpers automatically afterward — no extra configuration. Run `check_media_deps` to see what's ready, and `setup --uninstall` to remove them. ([Install by hand →](./docs/installation.md#local-helpers))\n\n### 3 · Ask\n\n> *“Summarize `demo.mp4`.”*\n\n## ✨ Capabilities\n\n| | |\n|--|--|\n| **Video** | Keyframe overview, full-size stills, scene detection, or a dense filmstrip that catches split-second glitches |\n| **Audio** | Speech turned into text — clips, voice notes, meetings, podcasts |\n| **Images** | The picture, plus the exact text shown on screen |\n| **Anywhere** | Local files or links — YouTube, Vimeo, and 1000+ sites |\n| **Private** | Runs on your machine. No API keys, no uploads |\n| **Efficient** | A long clip becomes a couple of images, not hundreds |\n\n## 🎞️ Modes\n\n`analyze_media` auto-detects audio and images. For video, choose how frames are sampled:\n\n| Mode | Best for |\n|------|----------|\n| `sheet` *(default)* | A cheap overview — frames tiled into one or two contact sheets |\n| `frames` | Detail on specific moments — individual full-size stills |\n| `scenes` | Slide decks & static screencasts — only scene-change frames |\n| `filmstrip` | Catching a sub-second UI glitch — a dense, near-native-rate strip |\n\n## 💬 Examples\n\nJust ask in plain language — the assistant picks the right options.\n\n| You ask | What you get |\n|---------|--------------|\n| *“Summarize `demo.mp4`.”* | A quick overview from sampled keyframes |\n| *“What error does `bug.mp4` show at the end?”* | The exact on-screen text, read back |\n| *“Walk me through the UI flow in `onboarding.mov`.”* | Step-by-step from scene-change frames |\n| *“Transcribe `standup.m4a` and list action items.”* | A local transcript |\n| *“Summarize `https://youtu.be/…` with the transcript.”* | Fetched and transcribed |\n| *“Read the error in this screenshot `crash.png`.”* | The picture plus its exact text |\n| *“Find where the slider in `ui.mp4` flickers ~0:06.”* | The exact frame of a sub-second glitch |\n\n## 🧰 Tools\n\n| Tool | What it does |\n|------|--------------|\n| **`analyze_media`** | Turn a video, audio, or image — file or URL — into model-readable context. Auto-detects the type and supports cropping, time windows, language, and sampling rate. |\n| **`check_media_deps`** | Report which capabilities are ready on this machine. |\n\nEvery call runs locally and cleans up after itself.\n\n## ⚙️ Options\n\nYour assistant fills these in for you, but you can steer it (“use filmstrip mode”, “crop to the toolbar”).\n\n
\nFull analyze_media parameters\n\n| Param | Default | Description |\n|-------|---------|-------------|\n| `source` | — | Local file path (video/audio/image) or http(s) URL |\n| `context` | — | A note framing the analysis; echoed atop the summary |\n| `detail` | — | `high` = readable stills for screen recordings; `low` = cheap overview |\n| `mode` | `sheet` | `sheet` · `frames` · `scenes` · `filmstrip` |\n| `format` | `webp` | `webp` (smallest) · `jpeg` · `png` (crisp text) |\n| `maxFrames` | `30` | Upper bound on sampled frames |\n| `grid` | `5` | Tiles per row/column for contact-sheet modes |\n| `scale` | `320` | Per-frame width in px — lower = fewer tokens |\n| `sceneThreshold` | `0.4` | Scene-change sensitivity (`scenes` mode) |\n| `fps` | auto | Explicit sampling rate; pair high with `filmstrip` |\n| `crop` | — | `{x,y,width,height}` (pixels, or `0–1` fractions) to zoom a region |\n| `stripRows` | `18` | Tiles per image in `filmstrip` mode |\n| `startSec` / `endSec` | — | Restrict to a time window |\n| `transcript` | `false` | Also produce a transcript (video) |\n| `whisperModel` | `small` | `tiny` · `base` · `small` · `medium` · `large` |\n| `ocr` | `false` | Extract on-screen text |\n| `ocrLang` | `eng` | Language code(s), e.g. `eng+deu` |\n| `ocrPsm` | `3` | Page-segmentation: `3` auto · `6` block · `11` sparse |\n| `detectJumps` | `false` | Track an on-screen number and report jump-back glitches with timestamps |\n| `maxDurationSec` | `3600` | Reject URL downloads longer than this |\n| `maxFileSizeMb` | `500` | Abort a URL download past this size |\n\nWorked recipes for each are in the **[usage guide](./docs/usage.md)**.\n
\n\n## ❓ FAQ\n\n**Can an LLM watch a video?** Not directly — models take images and text, not video. This server turns the video into frames and a transcript it can read.\n\n**Does anything get uploaded?** No. Everything runs on your machine; no keys, no cloud.\n\n**Which clients work?** Any MCP client — Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Cline, Kiro, Gemini CLI, JetBrains, Zed, Codex.\n\n**Does it handle YouTube and other links?** Yes.\n\n**How much does it cost?** It's free and open source.\n\n## 📋 Requirements\n\nNode.js 18+, on Windows, macOS, or Linux. The one-time `npx media-context-mcp setup` installs everything else.\n\n## 🛠️ Development\n\n```bash\nnpm install\nnpm run build\nnpm test\n```\n\nIssues and PRs welcome — see the [usage guide](./docs/usage.md) for the architecture.\n\n## 📄 License\n\n[Apache-2.0](./LICENSE) © Vishal Gupta\n", "bytes": 10118, "sha": "2927cc2675ae7e21e1df1f5677022cda9f7d3b97d3522567fea71415e0fd678e", "repo_slug": "vishalguptax/media-context-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_vishalguptax_media_context_mcp_dde76f60/readme" }