# 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](https://aistudio.google.com/app/apikey), and `yt-dlp` for social-video downloads (`brew install yt-dlp` on macOS or `pipx install yt-dlp` elsewhere).

```bash
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:

```bash
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:

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

Or ask a focused question:

```text
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:

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

```bash
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

```bash
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:

```bash
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](LICENSE)