A
licenseNot graded
qualityD
maintenanceEnables AI assistants to search through structured databases and unstructured content (documents, videos, files) using natural language queries with semantic understanding.
MIT
video-material-db
by JimmyChin756
Video Material DB（视频素材语义数据库）
一个面向短视频研究与创作的本地优先知识库。它将视频、字幕和 AI 结构化分析统一保存到 PostgreSQL，并通过 Web 界面、REST API 与 MCP 工具提供自然语言检索。素材和分析数据默认保存在用户自己的运行环境中。
主要功能
从本地文件、文件夹或公开视频链接导入素材
采集抖音、TikTok、YouTube、B站等平台的博主视频列表
自动完成视频预处理、语音转写、关键帧提取与视觉分析
提取人物、场景、镜头、对白、剧情结构、笑点与改编建议
使用 pgvector 建立语义索引，按自然语言搜索视频、台词和剧情元素
通过 FastAPI Web 界面管理素材与后台任务
通过 MCP 接入 Codex 等 AI 工具
支持素材去重、异步处理、失败重试和批量导出
Related MCP server: youtube-mcp
应用场景
短视频编剧查找剧情、台词、笑点、反转和镜头参考
内容团队建立可搜索的视频案例库与创意知识库
分析热门博主的内容结构、叙事节奏和视觉表达
从大量参考视频中寻找可复用的创作模式
为 AI 助手提供结构化、可追溯的视频研究资料
技术组成
Python 3.11+
FastAPI
PostgreSQL + pgvector
MCP Server
ffmpeg / ffprobe
通义千问兼容接口（ASR、视觉分析与向量嵌入）
快速开始
完整安装步骤见 INSTALL.md。素材默认保存在项目下的 ./data 本地目录。
python3 -m venv .venv
.venv/bin/pip install -e .
cp .env.example .env启动数据库后，分别运行 Web 服务和后台分析任务：
.venv/bin/video-db-api
.venv/bin/video-db-worker浏览器打开 http://127.0.0.1:8000/。
MCP 接入
codex mcp add video-material-db -- <仓库绝对路径>/.venv/bin/video-db-mcp可用工具包括 add_video_url、add_local_video、search_videos、search_dialogue、search_jokes、search_story_structure 和 get_video_detail。
数据与安全
公开仓库只包含通用程序源码。.env、API 密钥、视频文件、数据库内容、备份、本机路径及个人数据均不会进入版本控制。
Available Tools
8 toolsadd_local_videoD
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
TDQS
D1/5.0
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness1/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
add_video_urlD
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes |
TDQS
D1/5.0
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness1/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
build_remake_contextD
| Name | Required | Description | Default |
|---|---|---|---|
| video_id | Yes |
TDQS
D1/5.0
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness1/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_video_detailD
| Name | Required | Description | Default |
|---|---|---|---|
| video_id | Yes |
TDQS
D1/5.0
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness1/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_dialogueD
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes |
TDQS
D1/5.0
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness1/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_jokesD
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes |
TDQS
D1/5.0
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness1/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_story_structureD
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes |
TDQS
D1/5.0
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness1/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_videosD
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes |
TDQS
D1/5.0
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness1/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
8 tool updates
v0.2.1- First observed
add_local_video - First observed
add_video_url - First observed
build_remake_context - First observed
get_video_detail - First observed
search_dialogue - First observed
search_jokes - First observed
search_story_structure - First observed
search_videos
TDQS
C2.1/5.0
Scored across 8 tools
Disambiguation5/5
All tools have clearly distinct purposes. Adding via URL vs local file are distinct, and the various search tools target different content types (videos, dialogue, jokes, story structure), so there is no ambiguity in what each tool does.
Naming Consistency5/5
All tool names follow the same verb_noun pattern in snake_case: add_, search_, get_, build_. This is fully consistent across the entire set.
Tool Count5/5
8 tools is well-scoped for a video material database. The set covers ingestion (add), retrieval (search, get), and a specialized operation (build_remake_context) without unnecessary bloat.
Completeness4/5
The main workflows of adding, searching across content types, and retrieving details are covered. Minor gaps exist—no update/delete operations for videos and no general list all videos—but agents can work around these with the provided search tools.
Maintenance
ActivityStale
ResponsivenessNo recent community issues
Related MCP Connectors
Video analysis AI: transcripts, summaries, visual scenes/shots, clips, answers in natural language.
Video knowledge base for agents: search your library's transcripts, keyframes and on-screen text.
Edit video by talking to your AI — search footage, cut timelines, apply effects, add captions.
Shot breakdowns of video clips, plus logos and brand kits, for any AI assistant.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to watch YouTube videos by extracting frames at scene changes and visual references, pairing each frame with the exact words spoken at that timestamp. Provides dense frame-transcript interleaving for any model.32 npm5MIT
VZT Video-Intelofficial
AlicenseNot gradedqualityDmaintenanceSelf-hosted video intelligence pipeline that turns video into structured, citable, queryable JSON scene graphs, enabling AI assistants to analyze and search across video libraries without re-processing.10 npm1MIT- FlicenseNot gradedqualityDmaintenanceEnables natural language search through personal video collections, returning AI-generated descriptions and direct URLs to relevant 30-second video clips.-