📹 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/video-metadata-mcp@1.0.0

解决方案 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！

1. Fork 本仓库
2. 创建您的特性分支 (git checkout -b feature/AmazingFeature)
3. 提交您的更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开一个 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

📞 联系方式

如有问题或建议，欢迎联系：

微信: pickstar_loveXX

---

⭐ 如果这个项目对您有帮助，请给个 Star！