io.github.vishalguptax/media-context-mcp

LLMs 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.

🚀 Install

Two steps — add the server, then install the local helpers it uses.

1 · Add the server to your client

# Claude Code
claude mcp add media-context -- npx -y media-context-mcp

The launch command is always npx -y media-context-mcp. Pick your client:

Settings → Developer → Edit Config (claude_desktop_config.json):

{
  "mcpServers": {
    "media-context": { "command": "npx", "args": ["-y", "media-context-mcp"] }
  }
}

~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):

{
  "mcpServers": {
    "media-context": { "command": "npx", "args": ["-y", "media-context-mcp"] }
  }
}

.vscode/mcp.json — VS Code uses the servers key:

{
  "servers": {
    "media-context": { "command": "npx", "args": ["-y", "media-context-mcp"] }
  }
}

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "media-context": { "command": "npx", "args": ["-y", "media-context-mcp"] }
  }
}

cline_mcp_settings.json (the extension's MCP settings):

{
  "mcpServers": {
    "media-context": { "command": "npx", "args": ["-y", "media-context-mcp"] }
  }
}

.kiro/settings/mcp.json (project) or ~/.kiro/settings/mcp.json (user):

{
  "mcpServers": {
    "media-context": { "command": "npx", "args": ["-y", "media-context-mcp"] }
  }
}

~/.gemini/settings.json:

{
  "mcpServers": {
    "media-context": { "command": "npx", "args": ["-y", "media-context-mcp"] }
  }
}

settings.json — Zed uses context_servers:

{
  "context_servers": {
    "media-context": { "command": { "path": "npx", "args": ["-y", "media-context-mcp"] } }
  }
}

~/.codex/config.toml:

[mcp_servers.media-context]
command = "npx"
args = ["-y", "media-context-mcp"]

Settings → Tools → AI Assistant → Model Context Protocol → Add, then use command npx with args -y media-context-mcp.

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.

2 · Install the local helpers

One command sets up everything the server uses, via your OS package manager:

npx media-context-mcp setup          # core: keyframes, links, on-screen text
npx media-context-mcp setup --audio  # also enable transcription

The 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 →)

3 · Ask

“Summarize demo.mp4.”

✨ Capabilities

🎞️ Modes

analyze_media auto-detects audio and images. For video, choose how frames are sampled:

💬 Examples

Just ask in plain language — the assistant picks the right options.

🧰 Tools

Every call runs locally and cleans up after itself.

⚙️ Options

Your assistant fills these in for you, but you can steer it (“use filmstrip mode”, “crop to the toolbar”).

Worked recipes for each are in the usage guide.

❓ FAQ

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.

Does anything get uploaded? No. Everything runs on your machine; no keys, no cloud.

Which clients work? Any MCP client — Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Cline, Kiro, Gemini CLI, JetBrains, Zed, Codex.

Does it handle YouTube and other links? Yes.

How much does it cost? It's free and open source.

📋 Requirements

Node.js 18+, on Windows, macOS, or Linux. The one-time npx media-context-mcp setup installs everything else.

🛠️ Development

npm install
npm run build
npm test

Issues and PRs welcome — see the usage guide for the architecture.

📄 License

Apache-2.0 © Vishal Gupta