Video Intelligence MCP

Paste a permitted public video URL into Codex, Claude Code, or Kimi Code and ask for a detailed breakdown. This local MCP server downloads supported public media with yt-dlp, uploads it to Gemini, and returns a timestamped production brief covering shots, visual design, animation, motion, narration, music, sound effects, and editing.

It is built to be set-and-forget: no browser extension, no background daemon, and no per-chat copy/paste. Your AI client starts the local server only when it needs a video tool.

Install

Prerequisites: Node 20+, a Gemini API key, and yt-dlp for social-video downloads (brew install yt-dlp on macOS or pipx install yt-dlp elsewhere).

npx -y @solad/video-intelligence-mcp@latest setup

The animated setup saves the Gemini key in a user-only configuration file and connects Codex, Claude Code, and, where the installed version supports it, Kimi Code. It also installs the Codex skill that makes URL-based requests reliably select the video tool.

For a non-interactive setup:

npx -y @solad/video-intelligence-mcp@latest setup --api-key "$GEMINI_API_KEY" --client codex --client claude

Use it naturally

In any connected client, paste a URL and say:

Give me an insanely detailed production breakdown of this: https://...

Or ask a focused question:

At what timestamp does the logo animate in, and how is the movement made?

The MCP server exposes five tools:

Tool	Purpose
analyze_video	Download (when needed), analyze a URL or local video, and return a video_id.
ask_video	Ask Gemini any number of follow-up questions about a retained video session.
forget_video	Delete a retained Gemini upload and its local session record.
download_video	Save a user-provided public video privately on this computer.
video_intelligence_status	Check the local setup.

Support and limits

• Works with public URLs supported by the installed yt-dlp extractor. That commonly includes YouTube, TikTok, Instagram, X, Vimeo, and direct video files, subject to each site's current availability.
• Uses Gemini Files API for video analysis. The default model is gemini-3.6-flash; set GEMINI_MODEL to override it.
• A pasted public URL is treated as authorized by the caller. The project does not bypass DRM, paywalls, private links, logins, or access controls.
• Gemini commonly samples visual video input around 1 fps. Reports flag rapid cuts and fine details that need frame-by-frame verification.

Client setup without the wizard

Each client uses the standard local stdio MCP shape:

{
  "mcpServers": {
    "video-intelligence": {
      "command": "npx",
      "args": ["-y", "@solad/video-intelligence-mcp@latest", "serve"]
    }
  }
}

codex mcp add video-intelligence -- npx -y @solad/video-intelligence-mcp@latest serve
claude mcp add --scope user video-intelligence -- npx -y @solad/video-intelligence-mcp@latest serve
kimi mcp add --transport stdio video-intelligence -- npx -y @solad/video-intelligence-mcp@latest serve

Kimi's MCP command is available in newer Kimi Code releases; update it if kimi mcp is not recognized. The installer detects this and prints the correct next step.

Developer workflow

npm install
npm run check
npm run build
node dist/cli.js doctor

The client integrations point to the public npm package, so use node dist/cli.js serve with a local MCP configuration while developing. Run the setup wizard after publishing the package.

Publishing uses a scoped npm package:

npm login
npm publish --access public

Keep real API keys out of the repository; .env is ignored.

Privacy

Downloads are stored under the user-only Video Intelligence state directory and are not committed or shared. Analysis uploads are retained for follow-up prompts for 24 hours by default (set VIDEOINTEL_SESSION_HOURS, maximum 72); use forget_video to delete an upload immediately. Review Google's current policy before processing sensitive footage.

License

MIT