VidXP MCP server
2026년 11월 14일 커밋AI 클라이언트가 영상 내 음성, 소리, 장면, 동작 및 반복되는 얼굴을 검색하고, 검증 가능한 근거와 함께 인덱싱 및 검색할 수 있도록 지원합니다.
다른 이름 grayhatdevelopers/vidxp
- 스타
- 59
- Tools
- —
- 다운로드, 30일
- —
- 최신 버전
- —
- 마지막 커밋
- 2026년 11월 14일
- 라이선스
- MIT
VidXP MCP란?
VidXP은(는) MCP server입니다. AI 클라이언트가 영상 내 음성, 소리, 장면, 동작 및 반복되는 얼굴을 검색하고, 검증 가능한 근거와 함께 인덱싱 및 검색할 수 있도록 지원합니다.
프로젝트 README에서 생성된 요약
VidXP MCP server 정보
VidXP는 개발자와 AI 에이전트가 특정 순간을 묘사하는 방식으로 영상 라이브러리를 검색할 수 있게 해줍니다. 이 로컬 우선 엔진을 사용하면 사용자가 영상 컬렉션을 인덱싱하고 음성, 주변 소리, 시각적 장면 또는 복잡한 동작에 기반한 자연어 쿼리로 콘텐츠를 검색할 수 있습니다. Windows, Linux, Apple Silicon macOS에서 작동하도록 설계되어 개인 파일이나 프로젝트 파일을 자신의 기기에 안전하게 보관할 수 있습니다.
개발자는 Python 패키지, HTTP API 또는 Model Context Protocol을 통해 이러한 기능을 애플리케이션에 통합할 수 있습니다. 서버는 데스크톱 애플리케이션, uv를 사용하는 CLI, 또는 홈 서버용 Docker 컨테이너 등 다양한 배포 방식을 지원합니다. 인덱싱이 완료되면 시스템은 검색 결과 검증을 위해 프레임, 클립 또는 보드와 같은 검증 가능한 근거를 제공합니다. vidxp search speech, vidxp search sound, vidxp search action과 같은 특정 도구를 사용하면 단순한 타임스탬프가 아닌 의미론적 의미를 기반으로 미디어 콘텐츠를 정밀하게 검색할 수 있습니다.
활용 사례
- 1특정 대화 찾기누군가 말한 정확한 단어를 입력하여 영상 내의 특정 순간을 찾습니다.
- 2시각적 동작 검색화면에서 일어나는 움직임을 묘사하여 일련의 사건을 식별합니다.
- 3반복되는 인물 식별영상 파일 전체에서 여러 번 나타나는 특정 얼굴을 그룹화하고 찾습니다.
- 4오디오 이벤트 검색미디어 라이브러리 내에서 개 짖는 소리나 교통 소음 같은 특정 소리를 찾습니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
자동 검사
2026년 11월 14일에 실행됨전체 보고서 →아직 인증되지 않았습니다. 서버는 80점 이상의 점수, 심각한 결함 없음, 그리고 검사에 충분한 데이터를 갖추어야 합니다. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능grayhatdevelopers/vidxp is public and reachablegithub.com/grayhatdevelopers/vidxp ↗통과
- 패키지가 이 저장소를 소스로 명시검사되지 않음
- 빌드 출처(Sigstore 증명)검사되지 않음
- 오픈 소스 라이선스 (OSI)MITspdx.org/licenses/MIT.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-11-12github.com/grayhatdevelopers/vidxp ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음검사되지 않음
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
- 모델에 대한 숨겨진 지침 없음0 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨검사되지 않음
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기Find the moment, not the timestamp
VidXP makes one video—or an entire collection—searchable by meaning:
- Speech search: type what you remember someone saying and jump to the matching moments.
- Scene search: describe what appeared on screen and find the closest visual matches.
- Action search: describe something that happens over several seconds.
- Actor matching: find recurring faces within a video and export a highlighted video for a selected group.
Use it to search years of family videos, add video search to an editing workflow, or let an AI agent answer questions using evidence from your own video library. Your videos can stay on your machine.
Start here
Choose the setup that fits how you want to use VidXP.
1. Desktop app
Download the installer for Windows, Apple Silicon macOS, or Linux from GitHub Releases.
Connect an existing VidXP installation or let the desktop app manage an isolated runtime for you. See the Desktop installation instructions for supported setup options.
2. CLI and local AI assistants
For commands, scripts, and local AI assistants, install uv, then run:
# Install the CPU edition
uv tool install --python 3.14 --torch-backend cpu "vidxp[local-worker,mcp]"
# Check FFmpeg, download models, and verify the installation
vidxp init
vidxp prepare
vidxp doctor
# Print the settings for a local MCP client
vidxp mcp-config
Add the browser interface with:
uv tool install --python 3.14 --torch-backend cpu \
"vidxp[local-worker,mcp,frontend]"
vidxp ui
See the installation guide for client-specific MCP configuration, the HTTP API, and remote server setup.
3. Docker for a server
Run the published all-in-one image on a home server or another single machine:
# Download the search models into the persistent volume
docker run --rm -it \
-v vidxp-data:/var/lib/vidxp \
ghcr.io/grayhatdevelopers/vidxp:latest \
vidxp prepare
# Start the browser interface
docker run --rm --init \
-p 8501:8501 \
-v vidxp-data:/var/lib/vidxp \
ghcr.io/grayhatdevelopers/vidxp:latest
For a long-lived server, pin a published version instead of latest. For a
Coolify deployment, use the published -control and -worker images with
compose.coolify.yaml—no repository build is required.
See the Coolify guide for the complete setup.
What you can do today
- Build searchable libraries from individual videos or whole collections.
- Find speech, sound events, visual scenes, and multi-frame actions by description.
- Ask grounded questions and inspect the supporting boards, frames, or clips.
- Group recurring faces and render highlighted actor overlays.
- Keep personal, client, or project libraries separate.
- Use VidXP through the desktop app, browser, CLI, MCP, or HTTP API.
A first search
The browser app guides you through importing and indexing. The same flow from the command line is:
# Add a video
vidxp media import samplevideo.mp4 --json
# Index the returned media ID
vidxp index create <media-id>
# Find a visual moment
vidxp search scene "a yellow taxi on a city street"
# Find an action or event
vidxp search action "a person opens a door and walks outside"
# Find a sound event
vidxp search sound "a dog barking over traffic noise"
# Find something that was said
vidxp search speech "the bread just came out of the oven"
Results include the source video, timestamps, match score, and the evidence
used to find the moment. Add --media-id <media-id> to search only one video.
Run vidxp --help or vidxp <command> --help for the full command reference.
For applications and AI agents
Use the Python package to add selected VidXP capabilities directly to an application, or use the HTTP API when VidXP runs as a service.
MCP lets AI clients add and index videos, search a library, ask grounded questions, and return inspectable evidence such as boards, frames, and clips. A local client can start VidXP as a program on the same computer. A hosted client connects to a deployed VidXP server.
Codex plugin and skills
VidXP is distributed as a Codex plugin through a Git marketplace hosted in this GitHub repository. It includes three reusable workflows:
- install Desktop or the CLI and connect Codex;
- ingest and index videos; and
- find moments and return inspectable evidence.
Paste this into Codex:
Add https://github.com/grayhatdevelopers/vidxp as a Git plugin marketplace, install the VidXP plugin, then use its $vidxp-install skill to set up VidXP on this computer.
VidXP Desktop can perform the same setup from its Set up in Codex button.
Compatible AI clients can show an interactive upload and evidence-review view. Clients without that interface still receive the same workflow results through ordinary MCP tools.
- Python, HTTP, and MCP installation
- Local HTTP API and MCP server
- Premiere Pro extension
- ChatGPT and Codex plugin integration
- Optional capability packages
- Coolify server setup
Downloads and storage
First setup downloads only the models needed for the capabilities you select. VidXP shows the download size and destination before it starts.
The Desktop-managed Python runtime and its selected dependencies can use approximately 3 GiB.
| Capability | Approximate model download |
|---|---|
| Speech search | 2.64 GiB |
| Sound event search | 0.94 GiB |
| Scene search | 1.43 GiB |
| Action search | 0.93 GiB |
| Actor matching | 37 MiB |
A full local Desktop setup with every search capability uses approximately 9.0 GiB. Leave additional temporary space during installation and for indexes, source videos, and exported results.
By default, the CLI and desktop app share the same VidXP data directory:
| Platform | Default location |
|---|---|
| Windows | %LOCALAPPDATA%\VidXP |
| macOS | ~/Library/Application Support/VidXP |
| Linux | ${XDG_DATA_HOME:-~/.local/share}/VidXP |
Docker keeps the same data in the vidxp-data volume shown above.
Product roadmap
The next product improvements are focused on:
- labeling actor groups and matching the same person across different videos;
- more reliable face tracking across angle, lighting, motion, and occlusion;
- connecting visible people with the dialogue they are speaking;
- better search ranking, time ranges, and natural-language questions across a whole library;
- richer previews, timelines, filters, saved searches, and result playback;
- easier organization for large personal and project video collections;
- faster indexing and supported GPU acceleration; and
- smoother desktop updates, repair, and model management.
VidXP is in beta. Feedback about search quality, actor workflows, and real video-library use cases is especially useful.
Help and project links
- Installation and troubleshooting
- Desktop development
- Coolify deployment
- Changelog
- Issue tracker
- MIT license
Contributing
Contributions are welcome. Read the contribution guide before opening a pull request.
Credits
VidXP began as a student research project by:
The research was conducted with Dr Shahab Tahzeeb at NED University of Engineering and Technology and Saad Bazaz at Grayhat.
VidXP is now built by Grayhat and maintained by community contributors.
Email: info@grayhat.studio
VidXP MCP 질문
VidXP로 영상에서 무엇을 검색할 수 있나요?
음성, 소리 이벤트, 시각적 장면, 다중 프레임 동작, 반복되는 얼굴을 검색할 수 있습니다. 각 검색 결과에는 소스 영상, 타임스탬프, 일치 점수 및 근거 데이터가 포함됩니다.
MCP를 통해 AI 클라이언트에서 VidXP를 어떻게 사용하나요?
mcp extra를 설치한 후, vidxp mcp-config를 실행하여 로컬 MCP 클라이언용 설정을 출력합니다. MCP 클라이언트는 영상을 추가 및 인덱싱하고, 라이브러리를 검색하며, 근거에 기반한 질문을 할 수 있습니다.
영상이 제 컴퓨터를 벗어나나요?
아니요, VidXP는 로컬 우선(local-first) 방식으로 설계되어 영상이 사용자의 기기에 그대로 유지됩니다. 호스팅된 클라이언트를 사용하는 경우에만 배포된 VidXP 서버에 연결됩니다.
검색 모델은 디스크 공간을 얼마나 차지하나요?
모델 다운로드 용량은 배우 매칭용 약 37 MiB부터 음성 검색용 2.64 GiB까지 다양합니다. 모든 기능을 포함한 전체 로컬 설정에는 약 9.0 GiB가 필요합니다.
VidXP를 사용하려면 API key나 로그인이 필요한가요?
README에 따르면 데스크톱 앱, CLI, MCP 또는 HTTP API를 통해 로컬에서 VidXP를 사용하는 데 필요한 API key, 토큰 또는 OAuth 로그인은 언급되어 있지 않습니다.

