Memvid MCP Server

Memvid MCP服务器🎥

一种模型上下文协议（MCP）服务器，向AI客户端公开Memvid视频内存功能。此服务器允许您将文本、PDF和其他内容编码为视频内存格式，以实现高效的语义搜索和聊天交互。

🌟 特性

• 文本编码：将文本块或全文文档添加到视频内存中
• PDF处理：从PDF文件中提取和编码内容
• 视频存储大楼：生成数据的压缩视频表示
• 语义搜索：使用自然语言查询编码数据
• 聊天界面：与您的编码知识库进行对话
• 多连接支持：处理多个并发客户端连接
• 综合录井：详细记录到stderr进行调试
• 优雅地关闭：适当的资源清理和信号处理

📋 需求

• Python 3.10或更高版本
• uv包管理器
• memvid包
• MCP兼容客户端（例如Claude Desktop）

🚀 安装

1.设置环境

cd /memvid_mcp_server
uv venv --python 3.12 --seed
source .venv/bin/activate

2.安装依赖项

uv add -e .

使用Docker进行H.265编码

服务器自动管理Docker的安装和生命周期：

1. 自动Docker设置：如果没有安装Docker，服务器会自动安装
2. 容器管理memvid包处理自己的Docker容器构建和管理
3. 生命周期管理：Docker守护进程在MCP服务器启动时启动

memvid包（安装在venv中）包含所有必要的Docker配置，并将自动：

• 构建 memvid-h265 需要时使用容器
• 使用Docker进行H.265编码 codec='h265' 已指定
• 内部处理所有容器生命周期

无需手动设置Docker或外部存储库路径。h265using theDocker 文件located in thedocker目录。

一旦构建了Docker镜像， memvid 将在以下情况下自动检测并使用它 video_codec='h265' 在中指定 build_video.

3.测试服务器（可选）

uv run python memvid_mcp_server/main.py

⚙️ 配置

Claude桌面设置

1. 复制示例配置：

cp example_mcp_config.json ~/.config/claude-desktop/config.json

1. 或者手动添加到您的Claude Desktop配置中：

{
  "mcpServers": {
    "memvid-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/home/ty/Repositories/memvid_mcp_server",
        "run",
        "python",
        "memvid_mcp_server/main.py"
      ],
      "env": {
        "PYTHONPATH": "/home/ty/Repositories/memvid_mcp_server",
        "PYTHONWARNINGS": "ignore"
      }
    }
  }
}

1. 重新启动Claude Desktop以加载服务器。

🛠️ 可用工具

get_server_status

检查memvid服务器的当前状态，包括版本信息。

add_chunks

将文本块列表添加到编码器。

• 块：要添加的文本字符串列表

add_text

将单个文本文档添加到编码器。

• 文本：要添加的文本内容
• 元数据：可选元数据字典

add_pdf

处理PDF文件并将其添加到编码器。

• pdf_path：PDF文件的路径

build_video

从所有添加的内容构建视频内存。

• 视频路径：视频文件的输出路径
• 索引路径：索引文件的输出路径
• 编解码器：要使用的视频编解码器（'h265'或'h264'，默认值：'h265'）
• show_进度：是否在构建过程中显示进度（默认值：True）
• auto_build_docker：是否根据需要自动构建docker（默认值：True）
• 允许回退：是否允许回退选项（默认值：True）

search_memory

对构建的视频内存执行语义搜索。

• 怎么翻译：自然语言搜索查询
• top_k：要返回的结果数（默认值：5）

chat_with_memvid

与你的编码知识库进行对话。

• 消息：要发送到聊天系统的消息

📖 使用工作流程

1. 添加内容：使用 add_text, add_chunks，或 add_pdf 添加您的数据
2. 构建视频：使用 build_video 创建视频内存表示
3. 搜索或聊天：使用 search_memory 查询或 chat_with_memvid 用于对话

🔧 发展

测试

# Install development dependencies
uv add --dev pytest pytest-asyncio black ruff mypy

# Run tests
uv run pytest

# Format code
uv run black memvid_mcp_server/
uv run ruff check memvid_mcp_server/

调试

• 在Claude Desktop中检查日志： ~/Library/Logs/Claude/mcp*.log （macOS）或同等级
• 通过设置启用调试日志记录 LOG_LEVEL=DEBUG 在环境中
• 使用 get_server_status 检查服务器状态的工具

🔧 故障排除

常见问题

1. JSON解析错误：所有输出都正确重定向到stderr，以防止协议干扰
2. 导入错误：服务器优雅地处理丢失的memvid包，并显示清晰的错误消息
3. 连接问题：检查Claude Desktop日志并使用 get_server_status 诊断问题
4. 视频构建失败：确保有足够的磁盘空间和有效路径

日志记录配置

服务器实现了全面的stdout重定向，以防止任何库输出干扰MCP JSON-RPC协议：

• 所有memvid操作都包装有stdout重定向
• 捕获进度条、警告和模型加载消息
• 仅将结构化JSON响应发送到Claude Desktop
• 所有诊断信息都记录到stderr

错误消息

• “Memvid不可用”：安装memvid包： uv add memvid
• “未构建视频内存”：运行 build_video 在搜索或聊天之前
• “LLM不可用”：预期警告-memvid将在没有外部LLM提供商的情况下工作

📄 许可证

MIT许可证-有关详细信息，请参阅许可证文件。

🤝 贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

📚 相关项目

• Memvid -底层视频存储技术
• 模型上下文协议 -协议规范
• 克劳德桌面 -MCP兼容AI客户端

______________________________________________________________________

随着生产可靠性和MCP最佳实践的改进而产生。