Filesystem MCP

Filesystem MCP

AI アシスタントがファイルを安全に扱えるようにします。

選択したフォルダー内のファイルを読み取り、検索、編集、パッチ適用できます。
秘密のファイルは非表示のまま、リスクのある変更は確認を待ちます。

これは何ですか？

Model Context Protocol（MCP）は、Claude、VS Code の GitHub Copilot、Cursor などの AI アプリがツールに接続するための仕組みです。Filesystem MCP は MCP サーバーです。コンピューター上で実行され、AI にファイル操作用の 14 個のツールを提供する小さなプログラムです。使用できるフォルダーは自分で選択でき、それ以外の場所にはアクセスできません。

接続すると、次のようなことを依頼できます。

• 「このリポジトリ内の TODO をすべて見つけ、ファイルごとにまとめてください。」
• 「すべての .ts ファイルで getUser を fetchUser に名前変更してください。まず差分を見せてください。」
• 「config.dev.json と config.prod.json の間で何が変わりましたか？」
• 「server.log の末尾 50 行を読み取り、エラーを説明してください。」
• 「古いスクリーンショットを archive/2025/ に移動してください。」

Filesystem MCP を選ぶ理由

• デフォルトで安全です。AI が使えるのは許可したフォルダーだけで、.env ファイル、秘密鍵、クラウドの認証情報はブロックされます。AI が空でないフォルダーを削除する場合、許可していないフォルダーを開く場合、または create や move でファイルを上書きする場合、サーバーは事前に確認を求めます。確認を省略できるのは create とコピーだけで、その場合は overwrite: true を渡します。edit、patch、replace_text による編集は確認なしで適用されますが、dryRun を使えば、AI が先に差分を表示できます。AI に一切変更させたくない場合は、--read-only を指定すると、書き込みを行うすべてのツールが無効になります。
• 検索と編集はコード向けに作られています。AI は、ハングしない正規表現エンジン（RE2）を使って、grep のようにファイル内を検索できます。また、デフォルトではサーバーが .gitignore の対象ファイルや node_modules などのフォルダーをスキップします。編集は完全一致による置換で、テキストが一致しない場合はエラーを返します。また、事前に差分をプレビューできます。
• AI のコンテキストを節約できます。AI は1回の呼び出しで複数のファイルを読み込むことも、必要な行だけを読み込むこともできます。また、読み込む前にファイルのサイズとトークン数の推定値を確認できます。
• macOS、Linux、Windows で、stdio または HTTP を介して、あらゆる MCP クライアントと連携します。npx、Docker、ワンクリックで使える Claude Desktop 拡張機能を使ってインストールできるほか、これを基に独自のクライアントを構築することもできます。
• プライバシーが守られます。マシン上で動作し、テレメトリーはなく、ネットワーク通信も行いません。

リファレンスサーバーとの比較

このサーバーと公式の @modelcontextprotocol/server-filesystem の違いを、2026-10-11 に README と照合しました。

クイックスタート

メモ

Node.js 24 以降が必要です。node --version で確認してください。

1. MCP サーバーを AI アプリに追加します。以下からお使いのものを選んでください。
2. /path/to/project を、AI が使用できるフォルダーに置き換えます。複数のフォルダーを指定できます。
3. アプリを再起動し、「アクセスできるフォルダーはどれですか？」と尋ねます。

ヒント

VS Code は現在、開いているフォルダーをサーバーと共有するため、ワンクリックの VS Code インストールではパスの指定は不要です。他のアプリや HTTP 経由で使用する場合は、フォルダーを args に指定してください。AI がフォルダーはないと答える場合は、これで解決できます。

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
    }
  }
}

code --add-mcp '{"name":"filesystem","command":"npx","args":["-y","@j0hanz/filesystem-mcp@latest","/path/to/project"]}'

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
    }
  }
}

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
    }
  }
}

claude mcp add filesystem -- npx -y @j0hanz/filesystem-mcp@latest /path/to/project

/plugin marketplace add j0hanz/j0hanz-marketplace
/plugin install filesystem-mcp@j0hanz-marketplace

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "C:/path/to/project"]
    }
  }
}

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/project:/workspace:ro",
        "ghcr.io/j0hanz/filesystem-mcp:latest",
        "--read-only",
        "/workspace"
      ]
    }
  }
}

npm install -g @j0hanz/filesystem-mcp

✎ はファイルを変更します。--read-only を指定すると、これらのツールは削除されます。

検索および一覧表示ツールは、AI が明示的に求めない限り、隠しファイル、.gitignore の対象ファイル、および node_modules、dist、.git などのフォルダーをスキップします。

設定

ほとんどの場合、フォルダー引数だけで十分です。以下のオプションは一般的な用途をカバーします。

フラグは、たとえば ["-y", "@j0hanz/filesystem-mcp@latest", "--read-only", "/path/to/project"] のように、パッケージ名の後の args に指定します。

設定の完全なリファレンスでは、すべてのフラグと環境変数、シークレットファイルの完全な一覧、制限事項、API キーを使った HTTP の設定、Docker、トラブルシューティングについて説明しています。

セキュリティ

脆弱性を発見した場合は、非公開で報告してください。 SECURITY.md に報告方法が記載されています。

独自のクライアントを構築する

エージェント、エディタープラグイン、ウェブアプリ、CI ジョブ、スクリプトなど、独自のコードから Filesystem MCP を呼び出すこともできます。AI アプリと同じルールが適用されるため、許可されたフォルダーの外部にアクセスしたり、秘密ファイルを読み取ったりすることはできません。

import { Client } from '@modelcontextprotocol/client';
import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';

const dir = '/path/to/project';
const client = new Client(
  { name: 'my-app', version: '1.0.0' },
  { capabilities: { elicitation: { form: {} } }, versionNegotiation: { mode: 'auto' } },
);
client.setRequestHandler('elicitation/create', async () => ({ action: 'decline' }));
await client.connect(
  new StdioClientTransport({
    command: 'npx',
    args: ['-y', '@j0hanz/filesystem-mcp', dir],
    cwd: dir,
  }),
);

const result = await client.callTool({ name: 'search_text', arguments: { searchPattern: 'TODO' } });
const { matches } = (result.structuredContent ?? result._meta) as { matches: unknown[] };
console.log(matches);
await client.close(); // stops the server process; without it the script never exits

基本事項：

• データの場所。 テキストブロックはモデル向けに記述されています。同じデータは、独自のテキストを生成するツール（list、search_text、edit、...）では _meta に JSON として、stat、create、list_roots では structuredContent に格納されています。例外は read です。ファイルのテキストはテキストブロックにのみ含まれ、_meta にはファイルに関するメタデータが格納されています。
• パス。 相対パスは、サーバーの作業ディレクトリがルート内にある場合はその作業ディレクトリを基準に解決され、それ以外の場合はルートを基準に解決されます。複数のルートがある場合、パスはそのうちちょうど1つの配下に存在する必要があります。絶対パスが曖昧になることはありません。検索結果はルートを基準とする相対パスで表示されるため、そのまま渡し直すことができます。ディスク上の名前と異なるのが Unicode 形式（NFC または NFD）または空白文字（U+00A0、U+202F）だけの名前でも、そのエントリーが見つかります。
• 確認。 上書き、再帰的な削除、ルート外のパスについては、ユーザーへの確認が必要です。elicitation ケイパビリティを宣言してハンドラーで応答するか、2026-07-28 プロトコルではそれらをデータ（input_required）として受け取り、後で応答してください。
• プロトコルのバージョン。 サーバーは、stdio と Streamable HTTP 経由で、2025 プロトコルおよび 2026-07-28 に対応しています。HTTP 経由では、2025 年版のクライアントは確認や変更通知を受け取りません。
• リソース。 filesystem-mcp://file/{+path} として任意のファイルを読み取り、購読できます。internal://instructions と get-help プロンプトには、モデル向けのサーバーガイドが含まれています。

クライアントガイドに詳細があり、TypeScript および Python SDK でテストされています。また、examples/ には実行可能なクライアントが6つあります。

プライバシーポリシー

Filesystem MCP はすべてお使いのマシン上で動作します。このポリシーは、npm パッケージ、Docker イメージ、.mcpb デスクトップ拡張機能を対象としています。

• データ収集： ありません。サーバーはテレメトリー、分析、クラッシュレポートを行わず、外部へのネットワークリクエストも送信しません。
• 利用と保存： サーバーがファイルを読み書きするのは、許可されたフォルダー内で、MCP クライアントがツールを呼び出した場合に限られます。ツールの結果はそのクライアントに送られ、それ以外には送信されません。短期間の結果キャッシュと取り消し履歴（保存されたファイルの内容）はメモリ内に保持され、サーバーの終了時に消去されます。
• 第三者との共有： サーバーによる共有はありません。MCP クライアントは、そのクライアント独自のプライバシーポリシーに基づき、ツールの結果をモデルプロバイダーに送信する場合があります。
• 保持期間： サーバーはプロセスの終了後、何も保持しません。診断ログはお使いのマシン上の stderr に出力されます。MCP クライアントが独自のログファイルに保存する場合があります。
• お問い合わせ： https://github.com/j0hanz/filesystem-mcp/issues で Issue を作成するか、GitHub Security Advisories を通じて非公開でセキュリティ上の問題を報告してください。

貢献

バグ報告、アイデア、プルリクエストを歓迎します。まずは CONTRIBUTING.mdをご覧ください。セットアップ、ソースからのサーバーの実行方法、プルリクエストに必要なチェックについて説明しています。

Filesystem MCPが役に立った場合は、GitHubでスターを付けていただくと、ほかの人にも見つけてもらいやすくなります。

ライセンス

MIT