video-research-mcp

Analyze recordings, compare documents, and research topics from your MCP client. Gemini processes the supplied content; the server returns structured results, timestamps, and source references where the selected tool provides them. Optional Weaviate storage lets you search saved work across sessions.

Watch the demo · Get started · Browse the docs

Repository links point to the published source release. For the exact source and bundled guides of an installed registry version, use its source archive on PyPI.

Choose how to use it

The repository contains a research server, a Claude Code workflow bundle, and two optional video-production servers. Installing the workflow bundle connects the research server; the companion servers need separate setup.

The research server's default model is gemini-3.8-flash. Claude workflows use the active orchestration model. Installed registry packages, a source checkout, and a running MCP process can be different versions; check the running process before relying on a particular model or feature.

This implementation branch also provides bounded local acquisition, inspectable source frames, durable window analysis, deterministic image/clip exports and configurable model vision, image comparison, OCR inference and object crops. See native media, window analysis and image edits, OCR and export manifests and configured vision for their actual limits and optional runtime requirements. These source features have separate acceptance evidence and have not been published as a new registry release.

Install for Claude Code

You need Node.js 22 or later, Python 3.11 or later, uv, and a Gemini API key.

npx video-research-mcp@latest

The installer copies workflows into ~/.claude/, registers MCP servers in ~/.claude.json, and creates a configuration template at ~/.config/video-research-mcp/.env. Open that file and set GEMINI_API_KEY. Keep it private. Selected content is sent to the configured provider for analysis.

Restart Claude Code, inspect /mcp, and ask it to call infra_configure() without arguments. This reads the running configuration without making a Gemini request. Then use /gr:doctor quick to inspect the rest of the setup.

npx video-research-mcp@latest --check      # inspect installation
npx video-research-mcp@latest --local      # install in this project
npx video-research-mcp@latest --uninstall  # remove unchanged owned files and entries

Upgrades preserve custom settings and edited workflow files. The installer also registers Playwright and MLflow MCP; it does not start an MLflow tracking server or install the two video companions. See the setup guide for source installations, other clients, and troubleshooting.

Start with the work you have

For example:

/gr:video-chat ~/recordings/project-kickoff.mp4
Extract decisions and action items, with timestamps. Separate explicit decisions
from your interpretation, and identify anything the recording does not establish.

Commands can save notes, extract frames from local videos, and produce concept maps or screenshots. These outputs depend on the workflow and its prerequisites; ffmpeg is needed for local frame extraction. Direct MCP calls return tool data and do not run the whole Claude workflow.

Model-generated summaries, citations, transcripts, and evidence labels need checking against the original material when accuracy matters. A request for a complete transcript or every shared screen does not prove that the output covers all of them.

Use the server without Claude Code

Configure a stdio MCP server in your client's supported format. The following is a typical JSON registration; the shared environment file supplies credentials:

{
  "mcpServers": {
    "video-research": {
      "command": "uvx",
      "args": ["--refresh", "video-research-mcp"]
    }
  }
}

The npm installer targets Claude Code. Other clients, including Codex, can use the standard MCP server; their plugin, skill, and command installation formats differ. See other-client setup.

Add saved knowledge when you need it

Research works without Weaviate. To store and search analyses, configure a running Weaviate instance and its embedding provider:

WEAVIATE_URL=https://your-cluster.weaviate.network
WEAVIATE_API_KEY=your-weaviate-key

Analysis tools attempt to store their results when the connection is configured. Storage errors are non-fatal, so a successful analysis does not prove it was saved. The knowledge tools support search, related items, retrieval, ingestion, schema inspection, statistics, and optional QueryAgent answers. Graph extraction can make an additional Gemini request even when Weaviate storage is disabled.

The knowledge-store guide explains embeddings, collections, optional dependencies, permissions, and how to verify a stored result.

Configuration and costs

The server reads process environment variables first, then ~/.config/video-research-mcp/.env, then built-in defaults. A checkout .env is not loaded automatically.

Provider usage, Deep Research jobs, optional embeddings, and media generation can incur charges. The npm installer and MCP connection do not grant provider access or establish the quality of generated results. See the configuration guide and security policy before processing sensitive material.

Explore or contribute

• Documentation: setup, reference, and maintainer guides.
• Architecture: request flows and module responsibilities.
• Tool contracts: exact names and schemas.
• Contributing: development setup and verification.
• Roadmap and changelog: proposed work and release history.

The production skills cover image prompts, video generation, narration, and assembly. They provide guidance; they do not install external providers. The plugin-maintenance skill defines a bounded audit and repair workflow for this repository.

Author and credits

Created by Fausto Albers, Lead Gen AI Research & Development at the Industrial Digital Twins Lab, Amsterdam University of Applied Sciences, in Jurjen Helmus's research group, and founder of Wonder Why.

Built with Google Gemini, FastMCP, Pydantic, and optional Weaviate, MLflow, and Cohere integrations. Video companions use video_explainer, Claude Agent SDK, and the upstream pipeline's rendering and media providers.

Licensed under the MIT License.