Memdrive MCP

MemDrive

An MCP server that gives LLMs persistent memory on your own storage: a local folder (Google Drive / OneDrive / iCloud sync folder, or any plain directory). Local only, by design.

The model reads and writes Markdown + a sibling `assets/` image folder through six small tools. No cloud service, no account, no server to run — the MCP server runs on your own machine and touches only the folder you point it at.

Status: 0.8.2. Local filesystem backend only. Full-text search index with BM25 ranking (Chinese segmentation, filters, pagination, read-only diagnostics).

0.1.1 added one total response budget to read_file (see

Reading back and

Limits) and put the

clipboard rule first in the save_file tool description. 0.1.2 fixes

the preview ladder so previews use the budget instead of stopping

at the first coarse shrink step (see TEST-REPORT.md §7). 0.1.3 tries

higher JPEG quality at full resolution before shrinking, states the

three limit layers (host / server / model) in the read_file tool

description, and adds CHANGELOG.md (see TEST-REPORT.md §8). 0.2.0

adds open_image (open an original image in the OS viewer, only

when the user explicitly asks) and a setup wizard that finds a

sync folder and writes the Claude Desktop config for you (see

Setup and TEST-REPORT.md §9). 0.3.0

adds a Cursor adapter to the wizard: the wizard asks which host

to configure first and writes Cursor's global config

(~/.cursor/mcp.json) as well (see TEST-REPORT.md §12). 0.4.0

adds a VS Code adapter (Copilot Global config,

~/.copilot/mcp-config.json) and a per-host response budget

written by the wizard into each host's config (see

TEST-REPORT.md §13). 0.5.0 raises the Cursor budget to

10,000,000 on the 2026-10-30 verified read and adds

open_containing_folder (open a note's folder in the OS file

manager, only when the user explicitly asks, no highlight or

selection — see TEST-REPORT.md §14). 0.6.0 adds a Claude Code

adapter to the wizard (user scope, ~/.claude.json top-level

mcpServers, budget 10,000,000) — **UNVERIFIED on a real

machine, budget estimated by the author's decision, not

measured**; see Claude Code config and

TEST-REPORT.md §17.

Quick start

Requires Node.js 24+.

Easiest — setup wizard (recommended for first install). Download the release zip, extract it, and run the launcher for your system (it installs dependencies, builds, and starts the wizard, which asks which host to configure and which folder to use, and writes the Claude Desktop, Cursor, VS Code, or Claude Code config):

• Windows: double-click setup.bat
• macOS: double-click setup.command (or run ./setup.sh in a terminal)
• Linux: run ./setup.sh in a terminal

The wizard needs Node.js 24+ already installed; if it is missing, the launcher says so and offers to open https://nodejs.org for you. It never installs anything silently and never changes a config file without backing it up first (see Setup).

# 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

The library root defaults to ~/memdrive (created automatically). Override it with MEMDRIVE_ROOT:

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

Claude Desktop config

The setup wizard (see Setup) writes this for you. Only edit it by hand if the wizard could not find your config file — it then prints a ready-to-paste snippet instead.

Add this to your Claude Desktop config file (claude_desktop_config.json):

{

"mcpServers": { "memdrive": { "command": "npx", "args": ["-y", "memdrive-mcp"], "env": { "MEMDRIVE_ROOT": "/Users/you/Library/CloudStorage/GoogleDrive-you@example.com/My Drive/memory" } } } }

Point MEMDRIVE_ROOT at a folder your sync client already manages and the official client syncs everything to the cloud in the background — MemDrive itself does zero network auth and zero uploads.

On Windows use a Windows path (C:\\Users\\you\\OneDrive\\memory); on macOS/Linux use a POSIX path. Restart Claude Desktop after editing the config.

Cursor config

The setup wizard (see Setup) writes this for you, in Cursor's global config file: %USERPROFILE%\.cursor\mcp.json on Windows, ~/.cursor/mcp.json on macOS/Linux. If that file does not exist yet but the .cursor directory does, the wizard creates it (no backup is needed — there is nothing to back up); if the directory does not exist, the wizard writes nothing and prints a ready-to-paste snippet instead. Project-level .cursor/mcp.json files are not written: the global config makes the server available in every project. Only the Windows path has been verified on a real machine; the macOS/Linux paths use the same home-based logic and are marked untested.

{

"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" } } } }

The type: "stdio" field is required by Cursor; Claude Desktop entries carry no type field. The wizard writes the 10,000,000-byte budget above into Cursor's entry (see Limits for the evidence: verified 2026-10-30, exact ceiling unmeasured). Restart Cursor after editing the config, and make sure the server is enabled in Cursor's MCP settings. Cursor's MCP logs (Output panel → "MCP Logs") are the first place to look when a tool does not appear.

VS Code config

The setup wizard (see Setup) writes this for you, in VS Code's Copilot Global config file: %USERPROFILE%\.copilot\mcp-config.json on Windows, ~/.copilot/mcp-config.json on macOS/Linux. If that file does not exist yet but the .copilot directory does, the wizard creates it (no backup is needed — there is nothing to back up); if the directory does not exist, the wizard writes nothing and prints a ready-to-paste snippet instead. Only the Windows path has been verified on a real machine; the macOS/Linux paths use the same home-based logic and are marked untested. The COPILOT_HOME environment variable is not read — only the home-directory location above is used.

{

"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" } } } }

The entry shape above was verified on a real Windows machine (manual MCP: Add Server flow, Copilot Global config): top-level mcpServers, type: "stdio", command: "node", absolute dist/index.js args, and VS Code's own "tools": ["*"] field alongside them. When the wizard merges into an existing entry, that tools field is preserved, as are every other key and every other server; a freshly created entry gets no tools field. The wizard writes the 10,000,000-byte budget above into VS Code's entry (see Limits for the evidence: partly verified, exact ceiling unmeasured). Fully quit and restart VS Code after editing the config, and make sure the server is enabled in VS Code's MCP settings. VS Code's MCP logs are the first place to look when a tool does not appear. Only list_directory and a bundled image read have been verified in VS Code on a real machine so far; the other tools still need a real-machine check (see Roadmap).

Claude Code config

UNVERIFIED — read this first. The Claude Code adapter was

added from Anthropic's official docs only (checked 2026-10-31)

and has never been tested on a real machine, in any host.

The 10,000,000-byte budget below is an estimate set by the

author's decision (Claude Code is a paid product; a limit as

stingy as Claude Desktop's would make no sense for paying

users), not a measurement. If a bundled read fails or comes

back truncated in Claude Code, please report the exact error —

that report is how the default gets corrected.

The setup wizard (see Setup) writes this for you, in Claude Code's user scope: the top-level mcpServers key of the one ~/.claude.json file (%USERPROFILE%\.claude.json on Windows, ~/.claude.json on macOS/Linux). When CLAUDE_CONFIG_DIR is set, the file lives inside that directory instead. Local scope (per-project entries inside the same file) and project scope (.mcp.json in a project root) are not written: the wizard writes the user-global config only, so the server is available in every project. If ~/.claude.json does not exist, the wizard writes nothing and prints a ready-to-paste snippet instead — it never creates the file, because ~/.claude.json is Claude Code's own main state file (it also holds project records), not a dedicated MCP file, and creating a bare copy was never verified.

{

"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" } } } }

The entry carries no type field: Claude Code reads an entry without a type as a stdio server, the same shape as a Claude Desktop entry. The budget above controls only how much this server sends. Claude Code applies its own output limits on top (default 25,000 tokens per tool result; long text results are spilled to a file for the model to read back), so a large bundled read may arrive as a file reference rather than inline content. To raise Claude Code's own limit, set MAX_MCP_OUTPUT_TOKENS in the shell before starting Claude Code (for example MAX_MCP_OUTPUT_TOKENS=50000 claude). Check the connection with claude mcp list or the /mcp panel.

Optional: raise (or lower) the read_file total response budget if your client allows larger tool results than Claude Desktop's ~1 MB ceiling:

"env": {

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

The default is 950,000 bytes; values are clamped to 100,000–50,000,000. See Limits before raising it.

Setup wizard & launchers

node dist/index.js setup runs an interactive wizard (no new dependencies — plain Node readline). After npm publish, the same wizard runs as npx memdrive-mcp setup; until the package is published, use the zip + launcher form below.

What the wizard does, in order:

1. Chooses a host. The wizard asks which host to configure — 1 Claude Desktop, 2 Cursor, 3 VS Code, 4 Claude Code (Enter = 1). You can skip the question with an argument: node dist/index.js setup cursor (or setup claude / setup claude-desktop, setup vscode — only that one word, no vs-code / code alias, setup claude-code — only that spelling, code is not an alias). The argument is an optional shortcut for people who already know which host they want; the prompt is the default, foolproof path, including for npx memdrive-mcp setup and the launchers, which call the wizard with no argument. An unrecognised argument falls back to the prompt instead of guessing a host.
2. Finds a library folder. It probes for existing sync folders — OneDrive, Google Drive, iCloud — plus the ~/memdrive default, and shows a numbered menu. Google Drive on Windows is probed in three steps: the DriveFS