memdrive-mcp

MemDrive

一个 MCP 服务，让大模型在你自己的存储空间中拥有持久记忆：本地文件夹（Google Drive / OneDrive / iCloud 同步文件夹，或任意普通目录）。按设计，仅在本地运行。

模型通过六个小型工具读取和写入 Markdown 文件及其同级的 assets/ 图片文件夹。无需云服务、无需账户，也无需运行服务器——MCP 服务在你自己的机器上运行，只访问你指定的文件夹。

状态：0.8.2。 仅支持本地文件系统后端。全文搜索索引采用 BM25 排序（中文分词、筛选、分页、只读诊断）。 0.1.1 为 read_file 添加了一个总响应预算（参见 读取结果 和 限制），并将剪贴板规则放在 save_file 工具说明的首位。0.1.2 修复了预览阶梯逻辑，使预览会充分利用预算，而不是在第一次粗略缩小后就停止（参见 TEST-REPORT.md §7）。0.1.3 在全分辨率下先尝试更高的 JPEG 质量，再缩小图片；在 read_file 工具说明中列明了三个限制层级（宿主 / 服务 / 模型）；并新增了 CHANGELOG.md（参见 TEST-REPORT.md §8）。0.2.0 新增了 open_image（仅在用户明确要求时，在操作系统的图片查看器中打开原始图片）以及一个设置向导，可查找同步文件夹并为你写入 Claude Desktop 配置（参见 设置 和 TEST-REPORT.md §9）。0.3.0 为向导新增了 Cursor 适配器：向导会先询问要配置哪个宿主，并同时写入 Cursor 的全局配置 （~/.cursor/mcp.json）（参见 TEST-REPORT.md §12）。0.4.0 新增了 VS Code 适配器（Copilot 全局配置， ~/.copilot/mcp-config.json），以及由向导写入各宿主配置中的每宿主响应预算（参见 TEST-REPORT.md §13）。0.5.0 将 Cursor 预算提高到 10,000,000（基于 2026-10-30 的验证读取），并新增了 open_containing_folder（仅在用户明确要求时，在操作系统文件管理器中打开笔记所在的文件夹，不会高亮或选中内容——参见 TEST-REPORT.md §14）。0.6.0 为向导新增了 Claude Code 适配器（用户范围，~/.claude.json 顶层的 mcpServers，预算为 10,000,000）——未经真实机器验证，预算是作者估算的，并非实测结果；参见 Claude Code 配置 和 TEST-REPORT.md §17。

快速开始

需要 Node.js 24+。

最简单的方式——设置向导（推荐首次安装时使用）。 下载发布压缩包，解压后运行适用于你系统的启动器（它会安装依赖、构建并启动向导；向导会询问要配置哪个宿主以及要使用哪个文件夹，并写入 Claude Desktop、Cursor、VS Code 或 Claude Code 配置）：

• Windows：双击 setup.bat
• macOS：双击 setup.command（或在终端中运行 ./setup.sh）
• Linux：在终端中运行 ./setup.sh

向导需要预先安装 Node.js 24+；如果尚未安装，启动器会提示你，并提供打开 https://nodejs.org 的选项。它绝不会静默安装任何内容，也不会在备份前修改任何配置文件（参见 设置）。

# Run without installing (after this package is published to npm):
npx -y memdrive-mcp

# Or from a checkout:
npm install
npm run build
node dist/index.js

库根目录默认为 ~/memdrive（会自动创建）。 使用 MEMDRIVE_ROOT 可更改该目录：

MEMDRIVE_ROOT=~/Documents/memory npx -y memdrive-mcp

Claude Desktop 配置

设置向导（参见 设置）会为你写入此配置。只有当向导无法找到你的配置文件时，才需要手动编辑——此时向导会打印可直接粘贴的代码片段。

将以下内容添加到 Claude Desktop 配置文件（claude_desktop_config.json）中：

{
  "mcpServers": {
    "memdrive": {
      "command": "npx",
      "args": ["-y", "memdrive-mcp"],
      "env": {
        "MEMDRIVE_ROOT": "/Users/you/Library/CloudStorage/[email protected]/My Drive/memory"
      }
    }
  }
}

将 MEMDRIVE_ROOT 指向同步客户端已在管理的文件夹，官方客户端便会在后台将所有内容同步到云端——MemDrive 本身不会进行任何网络身份验证，也不会上传任何内容。

Windows 上请使用 Windows 路径（C:\\Users\\you\\OneDrive\\memory）；macOS/Linux 上请使用 POSIX 路径。编辑配置后，重启 Claude Desktop。

Cursor 配置

设置向导（参见 设置）会为你将以下内容写入 Cursor 的全局配置文件：Windows 上为 %USERPROFILE%\.cursor\mcp.json，macOS/Linux 上为 ~/.cursor/mcp.json。如果该文件尚不存在，但 .cursor 目录已存在，向导会创建该文件（无需备份——没有可备份的内容）；如果该目录不存在，向导不会写入任何内容，而是打印一段可直接粘贴的代码。不会写入项目级 .cursor/mcp.json 文件：全局配置会让每个项目都能使用该服务。只有 Windows 路径已在真实机器上验证；macOS/Linux 路径采用相同的基于主目录的逻辑，并标记为未经测试。

{
  "mcpServers": {
    "memdrive": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/memdrive-mcp/dist/index.js"],
      "env": {
        "MEMDRIVE_ROOT": "/absolute/path/to/your/library",
        "MEMDRIVE_RESPONSE_BUDGET_BYTES": "10000000"
      }
    }
  }
}

Cursor 要求使用 type: "stdio" 字段；Claude Desktop 条目不包含 type 字段。向导会将上述 10,000,000 字节预算写入 Cursor 条目（证据请参见限制：已于 2026-10-30 验证，确切上限尚未测量）。编辑配置后，请重启 Cursor，并确保在 Cursor 的 MCP 设置中启用了该服务。工具未显示时，首先查看 Cursor 的 MCP 日志（输出面板 → “MCP Logs”）。

VS Code 配置

设置向导（参见 设置）会为你将以下内容写入 VS Code 的 Copilot Global 配置文件：Windows 上为 %USERPROFILE%\.copilot\mcp-config.json，macOS/Linux 上为 ~/.copilot/mcp-config.json。如果该文件尚不存在，但 .copilot 目录已存在，向导会创建该文件（无需备份——没有可备份的内容）；如果该目录不存在，向导不会写入任何内容，而是打印一段可直接粘贴的代码。只有 Windows 路径已在真实机器上验证；macOS/Linux 路径采用相同的基于主目录的逻辑，并标记为未经测试。不会读取 COPILOT_HOME 环境变量——只使用上述主目录位置。

{
  "mcpServers": {
    "memdrive": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/memdrive-mcp/dist/index.js"],
      "env": {
        "MEMDRIVE_ROOT": "/absolute/path/to/your/library",
        "MEMDRIVE_RESPONSE_BUDGET_BYTES": "10000000"
      }
    }
  }
}

上述条目格式已在一台真实 Windows 机器上验证（手动执行 MCP: Add Server 流程，使用 Copilot Global 配置）：顶层 mcpServers、type: "stdio"、command: "node"、绝对路径的 dist/index.js 参数，以及 VS Code 自带的 "tools": ["*"] 字段。当向导合并到现有条目时，会保留该 tools 字段，以及其他所有键和其他所有服务；新建的条目则不包含 tools 字段。向导会将上述 10,000,000 字节预算写入 VS Code 条目（证据请参见限制：已部分验证，确切上限尚未测量）。编辑配置后，请完全退出并重启 VS Code，并确保在 VS Code 的 MCP 设置中启用了该服务。工具未显示时，首先查看 VS Code 的 MCP 日志。目前只有 list_directory 和读取捆绑图像已在真实机器上的 VS Code 中验证；其他工具仍需在真实机器上检查（参见路线图）。

Claude Code 配置

未经验证——请先阅读此处。 Claude Code 适配器仅根据 Anthropic 的官方文档添加（核查日期：2026-10-31），从未在任何主机的真实机器上测试过。 下方的 10,000,000 字节预算是作者自行设定的估算值（Claude Code 是付费产品；对付费用户来说，采用像 Claude Desktop 那样吝啬的限制毫无道理），并非实测值。如果 Claude Code 中捆绑读取失败或返回内容被截断，请报告确切错误——这类报告有助于修正默认值。

设置向导（参见设置）会在 Claude Code 的用户范围内为你写入此配置：写入唯一的 ~/.claude.json 文件（Windows 上为 %USERPROFILE%\.claude.json，macOS/Linux 上为 ~/.claude.json）的顶层 mcpServers 键。如果设置了 CLAUDE_CONFIG_DIR，文件则位于该目录中。不会写入本地范围（同一文件中的项目条目）或项目范围（项目根目录中的 .mcp.json）：向导只写入用户全局配置，因此该服务在每个项目中都可用。如果 ~/.claude.json 不存在，向导不会写入任何内容，而是打印一段可直接粘贴的配置片段——它绝不会创建该文件，因为 ~/.claude.json 是 Claude Code 自己的主状态文件（还包含项目记录），而不是专用的 MCP 文件，并且从未验证过创建一个空白副本是否可行。

{
  "mcpServers": {
    "memdrive": {
      "command": "node",
      "args": ["/absolute/path/to/memdrive-mcp/dist/index.js"],
      "env": {
        "MEMDRIVE_ROOT": "/absolute/path/to/your/library",
        "MEMDRIVE_RESPONSE_BUDGET_BYTES": "10000000"
      }
    }
  }
}

该条目不包含 type 字段：Claude Code 会将没有 type 的条目视为 stdio 服务，其结构与 Claude Desktop 条目相同。上方的预算只控制此服务发送的内容量。Claude Code 还会额外应用自身的输出限制（每个工具结果默认最多 25,000 个 token；较长的文本结果会写入文件，供模型回读），因此，大型捆绑读取可能会以文件引用而非内联内容的形式返回。若要提高 Claude Code 自身的限制，请在启动 Claude Code 前于 shell 中设置 MAX_MCP_OUTPUT_TOKENS（例如 MAX_MCP_OUTPUT_TOKENS=50000 claude）。使用 claude mcp list 或 /mcp 面板检查连接。

可选：如果你的客户端允许的工具结果大于 Claude Desktop 约 1 MB 的上限，可提高（或降低）read_file 的总响应预算：

"env": {
  "MEMDRIVE_ROOT": "...",
  "MEMDRIVE_RESPONSE_BUDGET_BYTES": "5000000"
}

默认值为 950,000 字节；数值会限制在 100,000–50,000,000 之间。提高限制前，请参阅限制。

设置向导与启动器

node dist/index.js setup 会运行一个交互式向导（不添加新依赖——使用纯 Node readline）。npm 发布后，也可以通过 npx memdrive-mcp setup 运行同一向导；在软件包发布之前，请使用下方的 zip + 启动器形式。

向导按以下顺序执行： 0. 选择主机。 向导会询问要配置哪个主机 — 1 Claude Desktop、2 Cursor、3 VS Code、4 Claude Code （按 Enter = 1）。你也可以通过参数跳过 此问题：node dist/index.js setup cursor （或 setup claude / setup claude-desktop、setup vscode — 仅支持这一个词，不支持 vs-code / code 别名， setup claude-code — 仅支持这种拼写，code 不是 别名）。该参数 是为已经知道要使用哪个主机的用户提供的可选快捷方式； 提示是默认且防错的路径，也适用于 npx memdrive-mcp setup 和启动脚本，它们调用 向导时不带参数。无法识别的参数会回退到 提示，而不是猜测主机。

1. 查找库文件夹。 它会探测现有的同步文件夹 — OneDrive、Google Drive、iCloud — 以及 ~/memdrive 默认文件夹，并显示带编号的菜单。Windows 上的 Google Drive 会分三步探测： DriveFS 安装文件夹必须存在，然后通过 PowerShell 卷标 探测来查找盘符，最后检查常见路径（G:\My Drive、H:\My Drive、……）是否 存在 — 绝不会假定某个盘符。你也可以输入自定义的绝对路径（会展开 ~）。如果所选文件夹不存在，则会创建。
2. 通过探测已知位置查找主机配置。 Claude Desktop：macOS 的 Application Support；Windows 上的 %APPDATA%\Claude，以及 %LOCALAPPDATA% 下的 Store/每用户 位置。Cursor：仅全局配置文件， Windows 上的 %USERPROFILE%\.cursor\mcp.json，以及 macOS/Linux 上的 ~/.cursor/mcp.json，仅当 .cursor 目录存在时才返回。VS Code：仅 Copilot 全局配置文件， Windows 上的 %USERPROFILE%\.copilot\mcp-config.json，以及 macOS/Linux 上的 ~/.copilot/mcp-config.json，仅当 .copilot 目录存在时才返回。Claude Code：仅用户 范围，即唯一一个 ~/.claude.json 文件顶层的 mcpServers 键（Windows 上为 %USERPROFILE%\.claude.json， macOS/Linux 上为 ~/.claude.json；如果设置了 CLAUDE_CONFIG_DIR，则位于该目录中），仅当 文件已存在时才返回。只有一个文件 → 使用该文件；有多个 → 由你选择一个；没有 → 不会写入任何内容，向导会打印可直接粘贴的代码片段。
3. 安全地写入配置。 先备份现有文件 （<file>.bak；如果备份已存在，则使用 <file>.bak-<timestamp>， 因此绝不会覆盖先前的备份）。随后合并 mcpServers.memdrive 条目（command: node、args: [<absolute path to dist/index.js>]、env: {MEMDRIVE_ROOT: <chosen folder>}， Cursor 和 VS Code 还包含 type: "stdio"，Cursor、VS Code 和 Claude Code 的 env 中还包含主机的响应预算 — 参见 限制；Claude Desktop 条目不包含预算 env，Claude Code 条目不包含 type 字段）。其他所有键和 其他所有服务都会保留，现有条目的 "tools": ["*"] 字段（VS Code）也会保留。对于 Cursor 和 VS Code，如果配置文件不存在，则会新建文件（主机目录已存在），无需备份。绝不会新建缺失的 Claude Desktop 或 Claude Code 文件。配置文件损坏时会完全中止写入 — 不会备份，也不会进行任何更改。随后会提示你完全退出并重启已配置的主机。

启动脚本（Windows 使用 setup.bat，macOS/Linux 使用 setup.sh， macOS 双击启动使用 setup.command）只是薄封装：它们 会检查 Node.js 24+，运行 npm install + npm run build（明确显示失败信息，并停止脚本），然后运行向导。所有逻辑都保留在 Node 中；脚本本身不包含任何配置。 Windows SmartScreen 说明。 如果你从互联网下载了 zip 文件，运行 setup.bat 时 Windows 可能会显示“Windows 已保护你的电脑”。这是 SmartScreen 对下载文件的反应，并不表示文件有问题：setup.bat 是纯文本文件——如果愿意，可以先用 Notepad 打开并阅读，再运行。要继续操作，请点击 更多信息，然后点击 仍要运行。本项目未使用代码签名（只有在项目开始产生收入后，付费证书才值得考虑）。

其他主机。 该向导会写入 Claude Desktop、Cursor、 VS Code 和 Claude Code 配置（Cursor 的全局配置、 VS Code 的 Copilot 全局配置、Claude Code 的用户范围配置）。 写入配置的代码封装在一个小型的逐主机适配器中，因此以后可以添加其他主机，但前提是先在真实设备上验证该主机的配置方式——有一个例外：Claude Code 的配置仅根据 Anthropic 官方文档添加，尚未验证（参见 Claude Code 配置）。 Codex/Gemini 是没有桌面配置文件的 CLI，Grok 没有桌面 MCP 配置方式，也不存在 Muse 桌面应用。只有在收到用户反馈后，才会在这四种主机之后添加新主机。

工具

工具	功能
list_directory(path?)	列出库目录的直接子项（默认列出根目录）。
search_files(keyword, path?, file_types?, tags?, date_from?, date_to?, modified_after?, modified_before?, exact_phrase?, limit?, offset?, rebuild_index?, diagnostics_only?)	全文搜索（使用 BM25 对文本块排序并附带摘要；中文查询会进行分词）。可按文件类型、标签、文件日期和修改时间筛选；支持精确短语匹配和分页（limit 默认为 20，最大为 200）；diagnostics_only 会返回只读的库报告。
save_file(path, content, mode?, images?)	写入文本（通常为 Markdown）。模式：new（默认，不允许覆盖）、overwrite、append。会自动创建父文件夹。说“把截图存下来”，模型就会传入 images: ["clipboard"]——服务会读取你电脑上的剪贴板；不要将图片粘贴到聊天中。
read_file(path, include_images?)	读取文本，或在单次响应、总响应预算范围内读取 Markdown 文件及其引用的图片。传入 include_images: false 可仅读取文本并返回图片路径列表（两步读取的第 1 步）。
open_image(path)	以原始画质在操作系统默认图片查看器中打开图片文件。仅在用户明确要求查看原图时使用——绝不自动打开，也绝不向模型返回图片字节。
open_containing_folder(path?)	在操作系统文件管理器中打开包含某个文件的文件夹（或直接打开该文件夹本身），不会突出显示或选中任何文件。仅在用户明确要求打开文件夹时使用——绝不自动打开，也绝不向模型返回文件夹内容。省略路径即可打开库根目录。

搜索：关键词与精确短语

关键词搜索会将中文查询拆分为单个字符，并对所有包含这些字符的笔记进行排序，因此即使某篇笔记只包含其中几个字符，仍可能作为较弱的匹配结果出现。这是有意为之：即使你只记得某个短语的一部分，也能找到相关内容。

如果结果杂乱，或者你想确认某个短语确实出现在笔记中，请改用精确短语搜索：只会返回原文中包含该短语的笔记。说“用精确短语搜 「第一段哨兵词」”，模型就会传入 exact_phrase。

回读：打包、分两步和单张图片

每次 read_file 响应都受同一个总预算限制（所有图片块的文本字节数和 base64 字节数之和，默认 950,000）。文本会优先返回；图片只能使用文本剩余的预算。如果图片无法容纳，会在内存中缩小以适应剩余预算，或附带说明后跳过——不会因为图片导致整个读取失败，也不会修改磁盘上的文件。读取方式有三种：

1. 打包读取（默认）。 对 Markdown 文件调用 read_file，会在一次响应中返回文本及其引用的图片。适合包含一两张小图片的短笔记。对于大型截图（例如磁盘上约 800 KB、编码为 base64 后约 1.1 MB），会在内存中缩小以适应预算，而不会像 0.1.1 之前那样导致整个响应超限。
2. 分两步读取（有多张图片，或有一张大图时）。 首先调用 read_file 并设置 include_images: false：你会得到文本以及引用图片的路径列表（相对于资料库的路径，例如 notes/assets/shot-....png）。然后对每个图片路径分别调用一次 read_file。每次直接读取图片时，都会独享全部预算，因此每张图片都能达到预算允许的最佳质量——这是以完整可用质量获取大型截图的方式。
3. 读取单张图片。 直接对图片路径调用 read_file，会返回该图片。它同样受总预算限制：图片能容纳时会原样返回，只有当图片本身超出预算（或超出每张图片 3.5 MB 的上限）时才会在内存中缩小。如果图片无论如何都无法容纳在预算内（例如内置解码器无法缩小的格式），结果会以文本说明情况，而不是返回错误。

查看原始图片：open_image

read_file 返回适应响应预算的预览图——足以阅读，但不一定保留原始像素。用户明确要求查看原图（“打开这张图片”“在系统里打开这张图”）时，open_image 会使用操作系统的默认图片查看器以完整质量打开文件（Windows/macOS 上为 Photos，Linux 上为默认查看器）。该工具只会返回简短的文本确认；不会向模型发送图片字节。

工具描述本身就写明了这一规则：只有在用户明确提出请求时，模型才能调用 open_image，不能在读取或保存后自动调用。打开查看器窗口会在用户屏幕上产生可见的副作用，未经请求弹出窗口是不可接受的。只有资料库根目录内的图片文件才能打开；非图片文件、目录、缺失文件和越出沙盒范围的路径都会被拒绝。查看器通过参数数组启动（绝不使用 shell 字符串），因此精心构造的文件名无法注入命令。

打开笔记所在文件夹：open_containing_folder

当用户明确要求在系统中打开笔记所在的文件夹（“打开文件夹”“在系统里打开这个笔记所在的文件夹”）时，open_containing_folder 会在操作系统的文件管理器中打开该文件夹（Windows 上为 Explorer，macOS 上为 Finder，Linux 上为默认文件管理器）。传入文件时会打开其父文件夹；传入文件夹时会打开该文件夹；路径为空时会打开整个知识库根目录。打开文件夹时不会突出显示或选中任何文件——不会使用 explorer /select，不会在 Finder 中选中文件，也不会以选中状态显示文件。

这条规则直接写在工具描述中，方式与 open_image 相同：只有用户明确提出请求时才会打开，绝不会在读取或保存后自动打开。该工具只会返回一条简短文本，确认已打开的文件夹；文件夹内容不会发送给模型（如需查看文件夹中的内容，请使用 list_directory）。只有知识库根目录内的路径才会打开；不存在的路径和越出沙盒范围的路径都会被拒绝，不会修改任何内容，并且会通过参数数组启动器打开文件夹（绝不使用 shell 字符串），因此精心构造的文件名也无法注入命令。在 Windows 上，文件夹会通过 shell 启动（cmd /c start "" explorer.exe /n,<path>，开关和路径合并为一个逗号分隔的参数），因此每次都会在新的 Explorer 窗口中打开，而不会在已打开的 Explorer 窗口中打开隐藏选项卡；图像文件仍通过常规查看器启动方式打开，不作更改。

保存图像

save_file 接受一个 images 数组，可混合使用三种来源。先说剪贴板，因为这是最容易弄错的一种：

• 字符串 "clipboard"——截图的首选方式。 只需告诉模型“把截图存下来”／“把剪贴板里的图存下来”。服务会直接从你自己的机器读取剪贴板。你不需要粘贴、上传或在聊天中发送图像；模型也绝不能声称自己无法读取剪贴板，或知识库仅支持文本。（这条规则写在 save_file 工具描述的最顶部，因此模型最先看到它。）
• 本地文件路径——例如 ~/Pictures/shot.png（会去掉引号并展开 ~）。
• http(s) URL——直接下载，不消耗任何令牌。

图像会保存到同级的 assets/ 文件夹中，并重命名为 <document-name>-<timestamp>.<ext>；对于 Markdown 文件，还会自动附加标准的 ![alt](assets/...) 引用。始终以完整画质保留原始文件。

**交互规则（内置于工具描述中）：**调用 save_file 前，模型必须向你展示确切的目标路径和文件名，并在聊天中征得你的确认。不会弹出对话框——确认在对话中完成。

剪贴板边缘情况

• 剪贴板为空或其中是文本而非图像：文本仍会保存；结果会提示你重新截图。
• 无头环境（Docker、服务器、NAS）：剪贴板捕获会报告不受支持，并建议改用文件路径或 URL。服务绝不会因剪贴板／图像错误而崩溃。

限制（全部在 src/config.ts 中定义，不在其他位置——响应预算除外，它也可以通过环境变量覆盖）

常量	值	含义
RESPONSE_BUDGET_DEFAULT_BYTES	950,000	单次 read_file 响应的默认总预算：文本块的 UTF-8 字节数与每个图像块的 base64 字节数合并计算。可通过 MEMDRIVE_RESPONSE_BUDGET_BYTES 覆盖，范围限制为 100,000–50,000,000（RESPONSE_BUDGET_MIN/MAX_BYTES）。向导会将按主机设置的覆盖值写入 Cursor、VS Code 和 Claude Code 的配置项（见下方按主机划分的表格）；Claude Desktop 和未知主机则使用此默认值。
TEXT_MAX_BYTES	1,000,000	read_file 返回的文本会在此处截断（并附带说明）——同时也会受总预算限制，两者取较小值。优先保证文本；图像只能使用剩余预算。
IMAGE_PREVIEW_MAX_BYTES	3,500,000	单张图像预览的上限（二进制字节）。图像预览会在内存中缩小至低于此上限，且低于剩余响应预算所允许的大小，两者取较小值。预览会先尝试以原始分辨率重新编码为 JPEG，依次尝试 JPEG 质量 95、90、80，然后再缩小；之后以质量 80 按 0.9 的步长缩小，并返回第一个符合预算的尝试结果。因此，预览尺寸会尽可能接近预算允许的最大值，而不是在第一次大幅缩小后就停止；如果原始分辨率已经符合预算，则会将剩余空间用于提升清晰度。磁盘上的原始文件绝不会被修改。

为什么要设置总预算？为什么是 950,000：Claude Desktop 会拒绝超过 1,048,576 字节的整个工具结果。旧的分段上限（文本 1 MB、每张图像 3.5 MB，且不检查合计大小）会让打包读取的结果超出此限制——在实际的 2026-10-28 测试中，一张 813.5 KB 的截图变成了约 1.11 MB 的 base64，导致整个读取结果被拒绝。950,000 为 JSON 封装和说明预留了约 98 KB 的余量。只有在客户端确实能接受更大的结果时，才提高预算；服务端无法检测客户端的限制（MCP initialize 不携带主机或限制信息，也不会识别 clientInfo），因此默认值保持在已知的最低上限，并视为适用于所有 Claude Desktop 方案和未知主机。这里有三种不同的限制——主机的结果上限、此服务的预算和 3.5 MB 单图上限，以及模型自身的像素数／令牌数缩放限制——read_file 工具说明中会列出这三种限制，因此模型无需猜测究竟是哪一种触发了限制。

按主机划分的响应预算（向导会将其作为 MEMDRIVE_RESPONSE_BUDGET_BYTES 写入每个主机的配置项；服务端无法识别主机，因此环境变量值是传递预算的唯一方式）。不要对 Cursor 和 VS Code 这两行的描述作超出证据范围的解读：Cursor 已经过验证，VS Code 经过了部分验证，且两者的确切上限均未测定。

宿主	限额	证据
Claude Desktop	950,000	已验证：2026-10-28 单变量实验——通过环境变量禁用限额后，同一组合读取连续两次因完全相同的 1,048,576 错误而失败；950,000 预留了约 98 KB 的空间，用于 JSON 封装和备注。
Cursor	10,000,000	已验证：2026-10-30 一次组合读取通过（notes/测试A.md，4 个不同的图片引用，include_images 默认为 true，测试限额为 50,000,000，耗时 26 秒，未出现宿主大小错误）；每张预览报告为在内存中缩小至 2.24 MB，原图未改动，总计约 8.96 MB 二进制数据 / 约 11.95 MB Base64；还剩约 2 MB 余量；未测出确切上限，测试梯级已结束。随后将测试行恢复为 10,000,000，并重新验证了正常读取。
VS Code	10,000,000	部分验证：2026-10-29 四张图片的组合读取通过（notes/测试A.md，4 份相同的 10.44 MB PNG 副本）；每张预览报告为 2 位小数时 2.24 MB，总计约 8.96 MB 二进制数据 / 约 11.95 MB Base64；还剩约 2 MB 余量；未测出确切上限，测试梯级已结束——不再进一步探测。
Claude Code	10,000,000	估算值，未经验证。 由作者于 2026-10-31 决定设置，从未在真实机器上测试：Claude Code 是付费产品，因此对付费用户设置像 Claude Desktop 那样严格的限额毫无道理；如果估算有误，用户报告结果过大错误就是反馈途径。Claude Code 除此服务端限额外还有自己的输出限额（每个工具结果默认 25,000 个 token；长文本结果会写入文件），因此此值只控制服务端发送的内容量。启动 Claude Code 前，可通过 MAX_MCP_OUTPUT_TOKENS 提高其自身限额。

ChatGPT、Grok 和其他宿主的限额均未经测试；对于未知宿主，统一采用 950,000 作为默认值，而不假设它们拥有未经验证的更高限额。

为什么是 3.5 MB：Base64 会将二进制数据膨胀至 4/3，因此 3.5 MB 会变成约 4.67 MB 的 Base64 文本，低于官方文档中查到的所有厂商图片上限 （Bedrock/Vertex 为 5 MB，Gemini 为 7 MB，Claude API 为 10 MB，OpenAI 为 20 MB）。 未经重新查阅这些文档，请勿调高此值。即使总限额调高至超过此值，单张预览仍受其限制。

其他限额：每个 read_file 响应最多包含 20 张引用图片（通常会先触及 总限额）； search_files 返回排序后的文本块（最多 200 个，支持分页），并将结果文本限制在 MEMDRIVE_SEARCH_MAX_BYTES（默认为 80 KB）； URL 下载超时时间为 30 秒，并设有 500 MB 的安全上限（用于防止磁盘耗尽，并非产品限额）。搜索 索引是存储在库外部（系统缓存目录）的缓存，会自动重建；启动后首次搜索时，索引可能 仍在构建，此时结果会回退为直接扫描（仅搜索关键字子串，且文件须小于 256 KB），并会说明这一点。

安全

• 根目录沙箱（强制）。 所有路径都限制在 MEMDRIVE_ROOT 内。所有 ../ 路径逃逸、根目录外的绝对路径，以及指向根目录外部的根目录内符号链接，都会被拒绝——包括尚未创建文件的父级路径中的符号链接。违规时会返回明确错误。
• 本地图片源是操作系统路径，而非库内路径。 save_file 图片条目（例如 ~/Pictures/shot.png）有意从根目录外读取；只有目标位置受沙箱限制。
• 不监听网络。 仅使用 stdio 传输；不对外暴露任何内容。
• 零原生依赖。 纯 JS 依赖树（MCP SDK、zod、 jimp）。无 node-gyp，无 C++ 构建，无 Sharp。
• 图片格式。 jimp（纯 JS 解码器）可读取 PNG/JPEG/GIF/BMP/ TIFF。低于预览限额的 WebP 文件会原样传递；超过限额时会报告错误（而非崩溃）；SVG 文件会作为文本返回，绝不会作为图片块返回；GIF 读取其第一帧。

使用 MCP Inspector 验证（第 1 步，零大模型成本）

npm run build
npx -y @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list
npx -y @modelcontextprotocol/inspector --cli node dist/index.js --method tools/call --tool-name list_directory

注意：Inspector CLI 会在自己的环境中启动服务，因此你在 shell 中设置的 MEMDRIVE_ROOT 可能不会传递给它——默认值为 ~/memdrive。交互式 Inspector UI（不带 --cli 运行 npx @modelcontextprotocol/inspector ）允许你显式设置环境变量。

开发

npm install
npm run build      # tsc, strict
npm run typecheck  # tsc --noEmit
npm test           # protocol tests: SDK Client over stdio (see TEST-REPORT.md)

SDK 版本已精确锁定（@modelcontextprotocol/sdk 1.32.2， v1.x 维护线），并已提交 package-lock.json。SDK 有一个使用独立包名的 v2 版本线；在有理由迁移之前，本项目会继续使用 v1.x。

路线图（不在此 MVP 范围内）

• 已在真实硬件上验证 Windows 剪贴板捕获（2026-10-28， 通过 Claude Desktop 保存截图）；macOS 剪贴板分支 仍仅根据有记录的操作系统模式实现——当时没有可用的 macOS 设备。0.1.3 质量阶梯通过了在 Claude Desktop 中的真实对话复测（2026-10-28：对 1.22 MB 的评论截图生成了 359.0 KB 的预览，原图未受影响）。
• 仍待在真实 Windows 设备上验证（参见 TEST-REPORT.md §14）：设置向导的 VS Code 全流程（主机提示词 选项 3 和 setup vscode 参数、创建/合并 Copilot Global 配置 并保留 "tools": ["*"]、重启 VS Code、 在 VS Code 中使用全部六个工具——目前仅验证了 list_directory 和读取随附图片）；向导的 Cursor 全流程（主机提示词和参数、创建全局配置、 重启 Cursor、在 Cursor 中使用工具和 read/save/open_image/ open_containing_folder）；在每个主机中打开一次文件夹的 open_containing_folder；以及 Claude Desktop 回归检查（其条目逐字节一致）；macOS 向导分支 （setup.command、iCloud/Google Drive 候选项、open）和 PowerShell Google Drive 探测均未在真实硬件上测试。 不计划进一步探测 Cursor 或 VS Code 的大小限制。

许可证

MIT — 参见 LICENSE。

支持

如果 MemDrive 为你节省了时间，你可以支持它的开发。谢谢！

• Ko-fi： ko-fi.com/newmannn91
• USDT（仅限 TRC-20）： 仅向下方地址发送 TRC-20 USDT。请勿发送其他代币或使用其他网络——这些资金无法追回。

TU9GBiQ1Ji1Fm5YECYThjcchTofj8B6uCD

• 微信支付： 扫描下方二维码。

微信用户可扫码赞赏。