使用说明
MCP深度视频服务器
一个包含可重用代码的monorepo MCP视频分析服务器 和示例 锻炼裁判 CLI应用程序。
包裹
packages/mcp-video-server
模型上下文协议（MCP）服务器为LLM驱动的视频分析提供14种工具：帧提取、运动检测、场景分割、音频转录和帧注释。专为Claude设计，但适用于任何兼容MCP的客户端。
看 doc/tool_index.md 以获取所有可用工具的完整参考。
examples/workout-judge
通过Pydantic AI使用Claude进行人工智能驱动的运动形式分析。使用 FrameExtractor 和 GridCompositor 使用三个自定义Pydantic AI工具直接导入Python。
examples/workout-judge-mcp
相同的锻炼分析，但通过以下方式作为子流程连接到MCP视频服务器 MCPServerStdio所有14个MCP工具均可通过 toolsets 参数--不需要本地工具定义。
workout-judge |
workout-judge-mcp |
|
|---|---|---|
| 视频工具 | 本地定义为Pydantic AI工具 | 由MCP视频服务器提供 |
| 工具来源 | FrameExtractor + GridCompositor 作为Python库导入 |
MCPServerStdio 子进程 |
| 可用工具 | 3（概述、部分、精确框架） | 所有14个MCP服务器工具 |
| 代理商deps | VideoAnalysisDeps 带提取器/合成器 |
无（工具来自MCP） |
快速开始
# Install all packages
uv sync
# Set your API key
export ANTHROPIC_API_KEY=your_key_here
# Run workout-judge (direct Python imports)
uv run workout-judge analyze example_videos/sample.mov
# Run workout-judge-mcp (MCP server as subprocess)
uv run workout-judge-mcp analyze example_videos/sample.mov
运行MCP服务器
子进程模式（stdio）
这是默认传输。服务器通过stdin/stdout进行通信，通常由MCP客户端自动启动。
# Run directly
MCP_VIDEO_ROOT=./example_videos uv run python -m mcp_video_server
# Or via the entry point
MCP_VIDEO_ROOT=./example_videos uv run mcp-video-server
HTTP模式（SSE）
对于远程或多客户端场景，请使用MCP CLI通过HTTP运行服务器：
# Install the mcp CLI if needed
uv pip install mcp[cli]
# Start an SSE server on port 8080
MCP_VIDEO_ROOT=./example_videos uv run mcp run --transport sse --port 8080 mcp_video_server.server:create_server
环境变量
| 变量 | 必填 | 描述 |
|---|---|---|
MCP_VIDEO_ROOT |
是 | 包含视频文件的目录 |
MCP_VIDEO_DEBUG |
否 | 设置为 1 启用调试输出 |
MCP_VIDEO_DEBUG_DIR |
否 | 自定义调试输出目录（默认： MCP_VIDEO_ROOT/.mcp_debug) |
MCP_VIDEO_CACHE_DIR |
否 | 自定义缓存目录（默认： MCP_VIDEO_ROOT/.mcp_cache) |
GROQ_API_KEY |
No | Groq API密钥用于快速音频转录 |
Claude桌面配置
将此添加到您的Claude桌面 claude_desktop_config.json:
{
"mcpServers": {
"video": {
"command": "uv",
"args": ["run", "--project", "/path/to/workout-judge", "python", "-m", "mcp_video_server"],
"env": {
"MCP_VIDEO_ROOT": "/path/to/your/videos"
}
}
}
}
Claude代码配置
回购包括 .mcp.json 为Claude Code配置服务器的文件。通过以下方式启用它：
# The .mcp.json is already present — just update MCP_VIDEO_ROOT if needed
# Claude Code will auto-detect and offer to enable the server
正在验证MCP服务器
使用MCP检查器在没有LLM的情况下交互式测试工具：
# Install the inspector
npx @anthropic-ai/mcp-inspector
# In the inspector UI:
# 1. Set transport to "stdio"
# 2. Command: uv
# 3. Args: run python -m mcp_video_server
# 4. Environment: MCP_VIDEO_ROOT=/path/to/videos
# 5. Click "Connect"
# 6. Browse tools, call list_videos, get_video_overview, etc.
或者以编程方式进行测试：
# Verify the server starts and lists tools
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}}}' | MCP_VIDEO_ROOT=./example_videos uv run python -m mcp_video_server
隔离测试视频处理器
在没有API键的情况下验证帧提取和网格组合：
uv run python -c "
from mcp_video_server import FrameExtractor, GridCompositor
ext = FrameExtractor('example_videos/sample.mov')
frames = ext.extract_key_frames(8)
GridCompositor().create_grid_image(frames).save('/tmp/grid_test.jpg')
print('Open /tmp/grid_test.jpg to verify')
"
存储库结构
workout-judge/
├── pyproject.toml # uv workspace root
├── packages/
│ └── mcp-video-server/ # MCP server (14 tools)
│ ├── pyproject.toml
│ └── src/mcp_video_server/
├── examples/
│ ├── workout-judge/ # CLI example (direct imports)
│ │ ├── pyproject.toml
│ │ └── src/workout_judge/
│ └── workout-judge-mcp/ # CLI example (MCP client)
│ ├── pyproject.toml
│ └── src/workout_judge_mcp/
└── doc/
├── mcp_video_server_spec.md # Full server specification
└── tool_index.md # Tool reference
需求
- Python 3.11+
- 紫外线
- ffmpeg（用于音频转录）
- 人类学API密钥（用于门诊判断示例）
视频格式说明
- 大多数H.264/AVC MP4和MOV文件都是开箱即用的
- 并非所有平台上的OpenCV都支持H.265/HEVC。使用以下方式进行预转换：
ffmpeg -i input.mp4 -c:v libx264 -crf 18 output.mp4
许可证
麻省理工学院
