📹 Video Metadata MCP
🚀 基于 Model Context Protocol (MCP) 的专业视频元数据管理服务器，提供完整的视频文件元数据读取、编辑和管理功能。
✨ 功能特性
- 📖 元数据读取 - 读取视频文件的完整元数据信息（格式、分辨率、时长、编解码器等）
- ✏️ 元数据编辑 - 修改标题、作者、描述、版权等元数据信息
- 🏷️ 标签管理 - 添加、删除、搜索视频标签
- 📦 批量处理 - 批量管理多个视频文件的元数据
- 🔍 智能搜索 - 根据多种条件搜索视频文件
- ⚡ 缓存优化 - 智能缓存机制提升性能
📋 系统要求
- Node.js 18+
- FFmpeg (自动包含在依赖中)
🚀 安装
推荐方式（使用 @latest 标签）
npx @pickstar-2002/video-metadata-mcp@latest
全局安装
npm install -g @pickstar-2002/video-metadata-mcp@latest
🔧 使用方法
在 IDE 中配置 MCP 服务
Cursor / Claude Desktop
在您的 MCP 客户端配置文件中添加：
{
"mcpServers": {
"video-metadata": {
"command": "npx",
"args": ["@pickstar-2002/video-metadata-mcp@latest"]
}
}
}
VS Code (使用 MCP 扩展)
{
"mcp.servers": {
"video-metadata": {
"command": "npx @pickstar-2002/video-metadata-mcp@latest"
}
}
}
直接运行
# 使用 @latest 标签（推荐）
npx @pickstar-2002/video-metadata-mcp@latest
# 或者全局安装后运行
video-metadata-mcp
🛠️ 可用工具
1. 📖 read_video_metadata
读取视频文件的完整元数据信息。
参数：
filePath(string): 视频文件的完整路径
返回： 包含视频完整元数据的JSON对象
2. ✏️ update_video_metadata
更新视频文件的元数据信息。
参数：
filePath(string): 视频文件的完整路径updates(object): 要更新的元数据字段
3. 🏷️ add_video_tags / remove_video_tags
管理视频标签。
参数：
filePath(string): 视频文件的完整路径tags(string[]): 标签列表
4. 🔍 search_videos
在目录中搜索视频文件。
参数：
directory(string): 要搜索的目录路径options(object): 搜索选项
5. 📦 批量操作工具
batch_update_metadata- 批量更新元数据batch_add_tags- 批量添加标签batch_remove_tags- 批量删除标签
📁 支持的视频格式
- 🎬 MP4 (.mp4)
- 🎞️ AVI (.avi)
- 📹 MOV (.mov)
- 🎥 MKV (.mkv)
- 📺 WMV (.wmv)
- 🌐 FLV (.flv)
- 🕸️ WebM (.webm)
- 📱 M4V (.m4v)
📝 使用示例
读取视频元数据
// 通过 MCP 客户端调用
{
"tool": "read_video_metadata",
"arguments": {
"filePath": "/path/to/your/video.mp4"
}
}
更新视频元数据
{
"tool": "update_video_metadata",
"arguments": {
"filePath": "/path/to/your/video.mp4",
"updates": {
"title": "我的视频标题",
"artist": "pickstar-2002",
"description": "这是一个示例视频",
"tags": ["教程", "演示", "MCP"]
}
}
}
🔧 开发
# 克隆仓库
git clone https://github.com/pickstar-2002/video-metadata-mcp.git
cd video-metadata-mcp
# 安装依赖
npm install
# 开发模式运行
npm run dev
# 构建
npm run build
❗ 疑难解答
常见问题及解决方案
🚨 问题：遇到 Connection closed 错误
这通常是由于 npx 缓存问题导致的。请按以下顺序尝试解决：
解决方案 1（首选）：确认使用 @latest 标签
npx @pickstar-2002/video-metadata-mcp@latest
解决方案 2（备用）：锁定到特定稳定版本
# 查看可用版本
npm view @pickstar-2002/video-metadata-mcp versions --json
# 使用特定版本（例如 1.0.0）
npx @pickstar-2002/[email protected]
解决方案 3（终极方案）：清理 npx 缓存
# 清理 npx 缓存
npx clear-npx-cache
# 或者手动删除缓存目录
# Windows: %USERPROFILE%\.npm\_npx
# macOS/Linux: ~/.npm/_npx
# 然后重新运行
npx @pickstar-2002/video-metadata-mcp@latest
🚨 问题：FFmpeg 相关错误
确保系统已安装 FFmpeg：
# Windows (使用 Chocolatey)
choco install ffmpeg
# macOS (使用 Homebrew)
brew install ffmpeg
# Ubuntu/Debian
sudo apt update && sudo apt install ffmpeg
🚨 问题：权限错误
在 Linux/macOS 上可能需要适当的文件权限：
# 给予执行权限
chmod +x node_modules/.bin/video-metadata-mcp
# 或使用 sudo（不推荐）
sudo npx @pickstar-2002/video-metadata-mcp@latest
🤝 贡献
欢迎提交 Issue 和 Pull Request！
- Fork 本仓库
- 创建您的特性分支 (
git checkout -b feature/AmazingFeature) - 提交您的更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 打开一个 Pull Request
📄 许可证
本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。
📞 联系方式
如有问题或建议，欢迎联系：
微信: pickstar_loveXX
⭐ 如果这个项目对您有帮助，请给个 Star！
