memdrive-mcp

MemDrive

LLM に、独自のストレージ上で永続的なメモリを提供する MCP サーバーです。ローカルフォルダー（Google Drive／OneDrive／iCloud の同期フォルダー、または任意の通常のディレクトリ）を使用します。設計上、ローカルのみで動作します。

モデルは、6 つの小さなツールを通じて Markdown と、同階層にある assets/ 画像フォルダーを読み書きします。クラウドサービスもアカウントも、実行するサーバーも不要です。MCP サーバーはユーザー自身のマシン上で動作し、指定されたフォルダーだけを操作します。

ステータス：0.8.2。 ローカルファイルシステムのバックエンドのみです。BM25 ランキングを使った全文検索インデックス（中国語の分かち書き、フィルター、ページネーション、読み取り専用の診断機能）を備えています。 0.1.1 では read_file にレスポンス全体の予算を 1 つ追加し（読み戻しと制限を参照）、save_file ツールの説明でクリップボードに関するルールを先頭に配置しました。0.1.2 ではプレビューの縮小手順を修正し、最初の大まかな縮小段階で停止せず、予算を使い切るまでプレビューを生成するようにしました（TEST-REPORT.md §7 を参照）。0.1.3 では、解像度を下げる前に元の解像度でより高い JPEG 品質を試すようにし、read_file ツールの説明に 3 つの制限レイヤー（ホスト／サーバー／モデル）を明記し、CHANGELOG.md を追加しました（TEST-REPORT.md §8 を参照）。0.2.0 では open_image（ユーザーが明示的に求めた場合に限り、OS のビューアーで元の画像を開く機能）と、同期フォルダーを見つけて 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 では、2026-10-30 に検証した読み取りで Cursor の予算を 10,000,000 に引き上げ、open_containing_folder（ユーザーが明示的に求めた場合に限り、OS のファイルマネージャーでノートのフォルダーを開く機能。ハイライトや選択は行いません。TEST-REPORT.md §14 を参照）を追加しました。0.6.0 では、ウィザードに Claude Code アダプター（ユーザースコープ、~/.claude.json のトップレベル mcpServers、予算 10,000,000）を追加しました。実機では未検証です。予算は測定値ではなく、作者の判断による推定値です。 詳細はClaude Code の設定と TEST-REPORT.md §17 を参照してください。

クイックスタート

Node.js 24 以降が必要です。

最も簡単な方法 — セットアップウィザード（初回インストールにおすすめ）。 リリースの zip ファイルをダウンロードして展開し、お使いのシステム用のランチャーを実行してください（依存関係をインストールしてビルドした後、ウィザードを起動します。ウィザードでは設定するホストと使用するフォルダーを確認し、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"
      }
    }
  }
}

type: "stdio" フィールドは Cursor で必須です。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 と同梱画像の読み取りのみです。ほかのツールは実機での確認が必要です（ロードマップを参照してください）。

Claude Code の設定

未検証 — まずお読みください。 Claude Code アダプターは、Anthropic の公式ドキュメントのみをもとに追加されました（2026-10-31 に確認済み）。どのホストでも、実機でのテストは一度も行われていません。 以下の 10,000,000 バイトの上限は、作者の判断による推定値です（Claude Code は有料製品であり、Claude Desktop のように厳しい上限では有料ユーザーにとって意味がありません）。バンドル読み込みに失敗したり、Claude Code で内容が途中で切れたりした場合は、正確なエラーを報告してください。その報告をもとにデフォルト値を修正します。

セットアップウィザード（セットアップを参照）は、Claude Code のユーザースコープでこの設定を書き込みます。書き込み先は、1 つの ~/.claude.json ファイルのトップレベルにある mcpServers キーです（Windows では %USERPROFILE%\.claude.json、macOS/Linux では ~/.claude.json）。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 トークン。長いテキスト結果は、モデルが読み返せるようファイルに書き出されます）。そのため、大きなバンドル読み込みはインラインコンテンツではなく、ファイル参照として届くことがあります。Claude Code 独自の上限を引き上げるには、Claude Code の起動前にシェルで 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 — この1語のみで、vs-code / code エイリアスはありません、 setup claude-code — この綴りのみで、code はエイリアスでは ありません）。引数は、設定したいホストがすでに決まっている 人向けの任意のショートカットです。引数なしでウィザードを 呼び出す npx memdrive-mcp setup やランチャーを含め、 質問形式がデフォルトの、間違いが起きにくい方法です。 認識できない引数が指定された場合、ホストを推測せず、 質問に戻ります。

1. ライブラリフォルダーを探します。 既存の同期フォルダー — OneDrive、Google Drive、iCloud — と ~/memdrive のデフォルト を調べ、番号付きメニューを表示します。Windows の Google Drive は3段階で調べます。まず 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： ユーザースコープのみ。1つの ~/.claude.json ファイル （Windows では %USERPROFILE%\.claude.json、macOS/Linux では ~/.claude.json、または CLAUDE_CONFIG_DIR が設定されている 場合はその中）の最上位にある mcpServers キーで、ファイルが すでに存在する場合にのみ対象となります。ファイルが1つなら それを使用します。複数なら選択できます。ファイルがない場合は 何も書き込まず、すぐに貼り付けられるスニペットを表示します。
3. 設定を安全に書き込みます。 既存のファイルは、先に バックアップします（<file>.bak。バックアップがすでに存在 する場合は <file>.bak-<timestamp> とし、以前のバックアップを 上書きしません）。mcpServers.memdrive エントリー （command: node、args: [<dist/index.js への絶対パス>]、 env: {MEMDRIVE_ROOT: <選択したフォルダー>}、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 が「PC は Windows によって保護されました」と表示することがあります。これはダウンロードしたファイルに SmartScreen が反応しているだけで、問題があることを示すものではありません。setup.bat はプレーンテキストなので、必要であれば実行前にメモ帳で開いて内容を確認してください。続行するには、詳細情報をクリックし、次に実行をクリックしてください。コード署名は使用していません（有料の証明書を取得する価値が出てくるのは、プロジェクトが収益を得るようになってからです）。

その他のホスト。 ウィザードは Claude Desktop、Cursor、VS Code、Claude Code の設定を書き込みます（Cursor はグローバル設定、VS Code は Copilot のグローバル設定、Claude Code はユーザースコープです）。設定を書き込むコードは、ホストごとの小さなアダプターに分離されているため、後から別のホストを追加できます。ただし、そのホストの設定仕様を実機で確認してからに限ります。例外が 1 つあります。Claude Code は Anthropic の公式ドキュメントのみをもとに追加されており、未検証です（Claude Code の設定を参照）。 Codex／Gemini はデスクトップ設定ファイルのない CLI であり、Grok にはデスクトップ向け MCP 設定機能がなく、Muse のデスクトップアプリもありません。これら 4 つのホストを対象に、ユーザーからのフィードバックを受けてから新しいホストを追加します。

ツール

ツール	機能
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 ファイルと、そのファイルが参照する画像を合わせて、1 回の応答で読み取ります（応答全体の上限内）。テキストと画像パスの一覧のみを取得する場合は、include_images: false を指定します（2 段階読み取りのステップ 1）。
open_image(path)	画像ファイルを OS のデフォルトの画像ビューアーで、元の画質のまま開きます。ユーザーが元画像の表示を明示的に求めた場合に限ります。自動では実行せず、画像データをモデルに返すこともありません。
open_containing_folder(path?)	ファイルを含むフォルダー（またはフォルダー自体）を OS のファイルマネージャーで開きます。ファイルをハイライト表示したり選択したりすることはありません。ユーザーがフォルダーを開くよう明示的に求めた場合に限ります。自動では実行せず、フォルダーの内容をモデルに返すこともありません。ライブラリのルートを開くには、パスを省略してください。

検索：キーワード検索と完全一致検索

キーワード検索では、中国語のクエリが 1 文字ずつに分割され、それらの文字を含むすべてのメモが順位付けされます。そのため、数文字しか一致しないメモも、関連度の低い結果として表示されることがあります。これは意図した動作です。フレーズの一部しか覚えていない場合でも、該当するものを見つけられます。

検索結果にノイズが多い場合や、あるフレーズが本当にメモに含まれているか確認したい場合は、代わりに完全一致検索を依頼してください。そのフレーズがそのまま含まれるメモだけが返されます。「用精确短语搜「第一段哨兵词」」と伝えると、モデルは exact_phrase を渡します。

読み戻し：パック読み込み、2段階読み込み、単一画像読み込み

すべての read_file レスポンスには、共通の合計予算が適用されます（すべての画像ブロックのテキストバイト数と Base64 バイト数の合計。デフォルトは 950,000）。テキストは必ず最初に返され、画像にはテキストで使用されなかった分だけが割り当てられます。収まらない画像は、残りの予算に合わせてメモリ上で縮小されるか、注記付きでスキップされます。画像が原因で読み込み全体が失敗することはなく、ディスク上のファイルが変更されることもありません。読み込み方法は3つあります。

1. パック読み込み（デフォルト）。 Markdown ファイルに対して read_file を実行すると、テキストと参照先の画像が1つのレスポンスで返されます。画像が1枚か2枚の短いメモに最適です。大きなスクリーンショット（たとえば、ディスク上で約800 KB、Base64 形式で約1.1 MB）は、0.1.1 より前のようにレスポンス全体を膨らませるのではなく、予算に収まるようメモリ上で縮小されます。
2. 2段階読み込み（画像が複数ある場合、または大きな画像が1枚ある場合）。 まず include_images: false を指定して read_file を呼び出します。テキストと、参照されている画像パスの一覧（ライブラリ相対パス。例：notes/assets/shot-....png）が返されます。次に、画像パスごとに read_file を1回ずつ呼び出します。画像を直接読み込むと、それぞれに予算全体が割り当てられるため、各画像で予算の許す限り最高の画質を維持できます。大きなスクリーンショットを、実用上可能な最高画質で取得するにはこの方法を使います。
3. 単一画像読み込み。 画像パスに対して read_file を直接実行すると、その画像だけが返されます。こちらにも同じ合計予算が適用されます。予算内に収まる場合、画像はそのまま返されます。画像自体が予算を超える場合（または1画像あたりの上限である3.5 MBを超える場合）に限り、メモリ上で縮小されます。画像を予算内に収められない場合（たとえば、組み込みデコーダーで縮小できない形式の場合）、エラーではなく、その理由を説明するテキストが返されます。

元の画像を表示する：open_image

read_file はレスポンスの予算に収まるプレビューを返します。画像を読むには十分ですが、元のピクセルがそのまま返されるとは限りません。ユーザーが元の画像を明示的に表示するよう依頼した場合（「この画像を開いて」「在系统里打开这张图」など）、open_image はオペレーティングシステムの既定の画像ビューアー（Windows／macOS では Photos、Linux では既定のビューアー）で、画質を落とさずにファイルを開きます。このツールが返すのは短いテキスト確認のみです。モデルに画像バイトが送信されることはありません。

このルールはツールの説明自体に記載されています。モデルが open_image を呼び出せるのは、ユーザーから明示的に依頼された場合に限られ、読み込みや保存の後に自動で呼び出してはなりません。ビューアーウィンドウを開くことは、ユーザーの画面に目に見える副作用をもたらします。依頼されていないポップアップは許容されません。開けるのはライブラリのルート内にある画像ファイルのみです。画像以外のファイル、ディレクトリ、存在しないファイル、サンドボックスの範囲外へのアクセスは拒否されます。また、ビューアーは引数配列で起動されるため（シェル文字列は使用しません）、細工されたファイル名からコマンドを注入することはできません。

ノートのフォルダーを開く：open_containing_folder

ユーザーがシステム上でノートのフォルダーを開くよう明示的にリクエストした場合（「フォルダーを開いて」「システム上でこのノートがあるフォルダーを開いて」など）、open_containing_folder は、そのフォルダーをオペレーティングシステムのファイルマネージャー（Windows では Explorer、macOS では Finder、Linux では既定のファイルマネージャー）で開きます。ファイルを指定すると親フォルダーが開き、フォルダーを指定するとそのフォルダー自体が開きます。パスが空の場合はライブラリーのルート全体が開きます。フォルダーを開く際にファイルが強調表示されたり選択されたりすることはありません。explorer /select、Finder での選択、選択状態での表示は行いません。

このルールは、open_image と同様にツールの説明自体に記載されています。ユーザーが明示的にリクエストした場合に限り、読み取りや保存の後に自動で実行されることはありません。ツールは、開いたフォルダー名を含む短い確認テキストのみを返します。フォルダーの内容はモデルに渡されません（フォルダー内を確認するには list_directory を使用してください）。ライブラリーのルート内にあるパスのみ開くことができます。存在しないパスとサンドボックスの外に出るパスは拒否され、何も変更されません。また、フォルダーを開く際には引数配列ランチャーを使用し（シェル文字列は使用しません）、細工されたファイル名からコマンドを注入できないようにします。Windows ではフォルダーをシェル経由で開きます（cmd /c start "" explorer.exe /n,<path>。スイッチとパスをカンマで結合した1つの引数にします）。そのため、すでに開いている Explorer ウィンドウの非表示タブではなく、毎回新しい Explorer ウィンドウで開きます。画像ファイルは引き続き通常のビューアーで開き、動作に変更はありません。

画像を含めて保存する

save_file は、3種類のソースを組み合わせた 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	1 回の 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	画像プレビュー 1 枚あたりの上限（バイナリバイト数）です。画像プレビューはメモリ上で、この上限と、残りのレスポンス予算で許容されるサイズのうち、小さいほうを下回るように縮小されます。プレビューの縮小では、まずフル解像度の 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 種類あります。ホストの結果上限、このサーバーの予算と画像 1 枚あたり 3.5 MB の上限、そしてモデル独自のピクセル数／トークン数による制限です。read_file ツールの説明にはこの 3 つすべてが記載されているため、モデルがどの制限に達したかを推測する必要はありません。

ホスト別のレスポンス予算です（ウィザードが各ホストの設定項目に MEMDRIVE_RESPONSE_BUDGET_BYTES として書き込みます。サーバーはホストを識別できないため、環境変数の値が予算を渡す唯一の方法です）。Cursor と VS Code の行について、記載された根拠以上のことを読み取らないでください。Cursor は検証済みで、VS Code は一部のみ検証済みです。また、どちらも正確な上限値は測定されていません。

ホスト	予算	根拠
Claude Desktop	950,000	検証済み：2026-10-28、単一変数の実験。環境変数で予算を無効にすると、同じバンドル読み取りが正確に 1,048,576 のエラーで 2 回失敗しました。950,000 なら、JSON のフレーミングと注記用に約 98 KB の余裕があります。
Cursor	10,000,000	検証済み：2026-10-30、単一のバンドル読み取りに成功しました（notes/测试A.md、個別の画像参照 4 件、include_images のデフォルトは true、テスト予算 50,000,000、26 秒、ホスト側のサイズエラーなし）。各プレビューはメモリ内で縮小されて 2.24 MB と報告され、元ファイルは変更されず、合計はバイナリで約 8.96 MB／base64 で約 11.95 MB でした。約 2 MB の余裕が残っています。正確な上限は測定しておらず、段階的な上限調査は終了しています。その後、テスト行を 10,000,000 に戻し、通常の読み取りを再検証しました。
VS Code	10,000,000	一部検証済み：2026-10-29、画像 4 枚のバンドル読み取りに成功しました（notes/测试A.md、10.44 MB の PNG の個別コピー 4 枚）。各プレビューは小数点以下 2 桁で 2.24 MB と報告され、合計はバイナリで約 8.96 MB／base64 で約 11.95 MB でした。約 2 MB の余裕が残っています。正確な上限は測定しておらず、段階的な上限調査は終了しています。これ以上の調査は行いません。
Claude Code	10,000,000	推定値、未検証。 作者の判断により 2026-10-31 に設定されました。実機では一度もテストされていません。Claude Code は有料製品であるため、Claude Desktop と同じように厳しい制限では、有料ユーザーにとって意味がありません。推定が誤っている場合は、サイズ超過エラーに関するユーザー報告をフィードバック経路とします。Claude Code では、このサーバー側の予算に加えて独自の出力制限も適用されます（ツールの結果あたりデフォルトで 25,000 トークン。長いテキスト結果はファイルに出力されます）。そのため、この値が制御するのはサーバーが送信する量のみです。Claude Code を起動する前に MAX_MCP_OUTPUT_TOKENS を設定して、Claude Code 側の制限を引き上げてください。

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 内に制限されます。../ による脱出、ルート外の絶対パス、ルート内にあってルート外を指すシンボリックリンクは すべて拒否されます。未作成ファイルの親ディレクトリにあるシンボリックリンクも対象です。 違反時には明確なエラーが返されます。
• ローカル画像のソースはライブラリのパスではなく、OS のパスです。 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 は独自の環境でサーバーを起動するため、シェルで設定した 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 のクリップボード処理は、 まだ文書化された OS パターンに基づいて実装しただけで、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 での 6 つすべてのツールの動作。これまで確認できたのは 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

• WeChat Pay： 下のコードをスキャンしてください。

WeChat ユーザーはコードをスキャンして寄付できます。