Filesystem MCP Server (@shtse8/filesystem-mcp)

Filesystem MCP

エージェントがリポジトリに手を加えました。プロジェクト内にとどまっていますか？

AI エージェント向けの、安全でトークン効率に優れたファイルシステム操作 — バッチ読み取り、ピンポイントな編集、シェルの起動オーバーヘッドなしでプロジェクトルート内に制限できます。

バッチ操作 · プロジェクトルートの安全性 · Zod による検証 · 13 個の MCP ツール · Docker 対応

エージェントがファイルごとにシェルを起動するのではなく、安全にコードベースを読み書きできるようにしたい場合は、⭐ このリポジトリにスターを付けてください。 · クイックスタート · 動作を見る · シェルコマンドではだめな理由 · ロードマップ

問題点

エージェントがコードを読み取り、編集を適用し、リポジトリ全体を検索するには、ファイルシステムへのアクセスが必要です。標準的な方法はシェルコマンドですが、操作ごとにプロセスを起動し、バッチ処理はできず、標準エラーの解析が必要で、パスがプロジェクトの外に出てしまう可能性があります。

その結果、トークンを消費し、遅延が増え、ファイルに触れるたびに信頼性の確認が必要になります。

Filesystem MCP は、エージェントがプロジェクトルート内に限定された、高速で制約のあるバッチ対応のファイル操作を必要とする場面のために作られています。

シェルコマンドではだめな理由

ベンチマークの仕様全体はこちら：docs/benchmark.md。

動作を見る

一度設定すれば、1 回の呼び出しで多数のファイルを読み取れます。

claude mcp add filesystem -- npx @sylphx/filesystem-mcp

{
  "paths": ["src/index.ts", "package.json", "README.md"]
}

read_content は、1 つの応答でファイルごとの結果を返します。

{
  "results": [
    { "path": "src/index.ts", "content": "...", "success": true },
    { "path": "package.json", "content": "...", "success": true },
    { "path": "README.md", "content": "...", "success": true }
  ]
}

重要： MCP サーバーは、cwd をプロジェクトルートに設定して起動してください。すべてのパスはそのディレクトリを基準とした相対パスです。

エージェントが利用する理由

クイックスタート

Claude Code

claude mcp add filesystem -- npx @sylphx/filesystem-mcp

cwd がリポジトリのルートになるよう、プロジェクトディレクトリから実行してください。

Claude Desktop／任意の MCP ホスト

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "npx",
      "args": ["@sylphx/filesystem-mcp"]
    }
  }
}

ホストの作業ディレクトリをプロジェクトのルートに設定してください。

Docker

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/path/to/your/project:/app",
        "sylphx/filesystem-mcp:latest"
      ]
    }
  }
}

ローカル開発

git clone https://github.com/SylphxAI/filesystem-mcp.git
cd filesystem-mcp
bun install
bun run build
bun run test

MCP ツール一覧

リリースの検証

リリースに関する主張は、CI の benchmark:release-gate、安全性フィクスチャコーパス、および出荷対象パスのマトリックス（主要ツールは Rust がデフォルト）によって裏付けられています。

bun run benchmark:release-gate

成果物：benchmark-artifacts/filesystem_release_gate.json — リリース前に status: passed と表示されている必要があります。

パフォーマンスベンチマーク

出荷される Rust CLI パスでローカルのスループットを再現します。

bunx vitest bench __tests__/benchmarks/throughput.bench.ts --run

シナリオ、設計目標、結果の解釈方法については、docs/benchmark.md を参照してください。

セキュリティモデル

• すべての操作は、サーバーの起動時の cwd 内に制限されます。
• 絶対パスは拒否され、パストラバーサルはブロックされます。
• Zod スキーマですべてのツール引数を検証します。
• バッチツールは項目ごとのステータスを返すため、1 件の失敗でほかの結果が隠れることはありません。

ドキュメント

開発

bun run validate    # lint + typecheck + test
bun run docs:build  # VitePress + API docs
bun run benchmark   # vitest bench

サポート

• Issue
• ディスカッション
• npm パッケージ

より多くの開発者にこのプロジェクトを届ける

エージェントのファイルごとのシェル操作でトークンを消費したり、パスの安全性への信頼を損なったりしたことがあるなら、このプロジェクトはあなたのためのものです。

⭐ リポジトリにスターを付ける — より多くのエージェント開発者が、安全でバッチ処理に適したファイルシステムアクセスを見つける助けになります。

ディレクトリへの掲載（進行中）

ほかの MCP ディレクトリをご存じですか？リンクを添えてIssue を作成してください。

ライセンス

MIT © Sylphx