Filesystem MCP：讓 AI 安全地操作你的檔案系統

當你使用 AI 編碼助手時，是否希望它能夠：

• 直接讀取檔案：無需手動複製貼上檔案內容
• 批量處理檔案：一次操作多個檔案或目錄
• 安全的檔案寫入：在受控範圍內修改檔案
• 動態探索專案結構：自動發現和分析檔案

Filesystem MCP 是 Anthropic 官方提供的 Model Context Protocol 服務器，專門為 AI 助手提供安全、可控的檔案系統操作能力。

2026 年 11 月 4 日更新： 依伺服器目前的 README 與 Claude Code v2.1.318 校正：以 --scope user 取代不存在的 --scope global；user 與 local scope 的伺服器存放在 ~/.claude.json，不是 ~/.claude/.mcp.json；由於 Roots 自 MCP 協定版本 2026-07-28 起已被棄用，現在建議用命令行參數指定允許的目錄；Docker 設定與工具名稱（read_text_file、search_files）也已改為與伺服器一致。

什麼是 Filesystem MCP？

Filesystem MCP 是一個基於 Node.js 的 MCP 服務器，實作了 Model Context Protocol 的檔案系統操作介面，讓 AI 助手能夠在嚴格的權限控制下讀寫本地檔案。

核心特色

1. 靈活的權限控制 🔒

   • 透過命令行參數指定允許存取的目錄
   • 2025 年版協定的客戶端可透過 Roots 在運行時更新權限（自 MCP 協定版本 2026-07-28 起已棄用）
   • 預設禁止所有未授權的目錄存取

2. 豐富的檔案操作 📁

   • read_text_file() - 以文字讀取檔案內容（read_file 是已棄用的別名）
   • read_media_file() - 以 base64 讀取圖片、音訊等二進位檔案
   • write_file() - 寫入或覆蓋檔案
   • edit_file() - 行級編輯（搜尋與替換）
   • list_directory() - 列出目錄內容
   • create_directory() - 建立目錄
   • move_file() - 移動或重新命名檔案
   • search_files() - 使用 glob 模式搜尋檔案
   • get_file_info() - 取得檔案元資料

3. 安全性優先 🛡️

   • 沙箱機制防止存取未授權目錄
   • 可設定唯讀模式（Docker 支援 ro flag）
   • 支援環境變數配置，避免硬編碼路徑

4. 現代化整合 ⚡

   • 在 stdio 上同時支援兩個 MCP 協定世代（2026-07-28 與 2025 年版客戶端）
   • Roots 僅適用於 2025 年版客戶端（已棄用；建議改用命令行參數）
   • 與所有 MCP 相容客戶端無縫整合

為什麼需要 Filesystem MCP？

問題：手動檔案操作的低效率

在沒有 Filesystem MCP 之前，AI 助手處理檔案的方式：

1. 用戶手動複製貼上 → AI 無法主動探索專案
2. 有限的內容視野 → 只能看到用戶提供的片段
3. 無法批量操作 → 每個檔案都需要手動處理
4. 修改需要人工介入 → AI 只能建議，無法執行

解決方案：安全的自主檔案操作

Filesystem MCP 讓 AI 能夠：

• ✅ 主動讀取相關檔案，理解完整上下文
• ✅ 批量處理多個檔案（重構、格式化、遷移）
• ✅ 直接寫入修改，減少人工複製貼上
• ✅ 探索專案結構，自動發現相關檔案

同時保持安全性：只能存取你明確授權的目錄。

安裝與設定

透過 npx 執行時，伺服器需要 Node.js 24 以上版本。

方法一：使用官方 CLI（推薦）

# 安裝到專案，允許存取當前目錄
claude mcp add \
  --scope project \
  filesystem \
  -- npx -y @modelcontextprotocol/server-filesystem \
  "$(pwd)"

# 安裝到你所有的專案（user scope），允許存取多個目錄
claude mcp add \
  --scope user \
  filesystem \
  -- npx -y @modelcontextprotocol/server-filesystem \
  /Users/username/projects \
  /Users/username/documents

方法二：手動配置

編輯專案根目錄的 .mcp.json（project scope）。user 與 local scope 的伺服器存放在由 Claude Code 代為管理的 ~/.claude.json，請改用 claude mcp add 新增：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/path/to/other/allowed/dir"
      ]
    }
  }
}

方法三：Docker 沙箱模式

使用 Docker 提供更嚴格的隔離：

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--mount", "type=bind,src=/path/to/project,dst=/projects/project,ro",
        "mcp/filesystem",
        "/projects"
      ]
    }
  }
}

提示：把每個目錄掛載到 /projects 底下，並以 /projects 作為允許的目錄。ro 選項會讓該掛載變成唯讀，AI 只能讀取不能修改。

Roots vs. 命令行參數

推薦方式：命令行參數

{
  "command": "npx",
  "args": [
    "-y",
    "@modelcontextprotocol/server-filesystem",
    "/allowed/dir1",
    "/allowed/dir2"
  ]
}

這是唯一在所有 MCP 協定版本上都能運作的方式，因此伺服器的 README 推薦使用。

限制：修改權限需要重啟服務器。

已棄用：Roots 協定（僅限 2025 年版客戶端）

Roots 是 MCP 的機制，讓客戶端動態暴露檔案系統邊界給服務器。以 2025 年版協定連線且支援 Roots 的客戶端，可以在運行時替換允許的目錄：

• ✅ 運行時更新權限（無需重啟）
• ✅ 通過 roots/list_changed 通知自動同步

Roots 自 MCP 協定版本 2026-07-28 起已被棄用，2026-07-28 的連線無法使用。Claude Code 的 v2 MCP runtime 會詢問 stdio 伺服器是否支援這個版本，並對支援的伺服器採用它，而這個伺服器正好支援，所以在 Claude Code 中請用命令行參數傳入允許的目錄。

不要在沒有指定目錄的情況下啟動伺服器、只靠 Roots：如果 2025 年版客戶端不支援 Roots，伺服器會在啟動時結束；在 2026-07-28 的連線上，每次工具呼叫都會回傳錯誤。

實際使用範例

範例一：專案重構

你：「把所有 .js 檔案中的 var 改成 const」

Filesystem MCP 自動執行：
1. search_files("/Users/username/project", "**/*.js") → 找到所有 JS 檔案
2. 對每個檔案執行 read_text_file()
3. 分析並生成修改建議
4. 使用 edit_file() 批量替換 var → const
5. 回報修改結果

結果：5 分鐘完成 50 個檔案的重構

範例二：專案結構分析

你：「分析這個專案的架構，畫出模組依賴圖」

Filesystem MCP 自動執行：
1. list_directory("/Users/username/project") → 獲取根目錄結構
2. search_files("/Users/username/project", "**/*.ts") → 找到所有 TypeScript 檔案
3. read_text_file() 讀取每個檔案的 import 語句
4. 分析依賴關係
5. 生成 Mermaid 圖表

結果：自動生成完整的專案架構圖

範例三：檔案批量處理

你：「把 src/components 下的所有 TypeScript 檔案加上 copyright header」

Filesystem MCP 自動執行：
1. list_directory("/Users/username/project/src/components")
2. search_files("/Users/username/project/src/components", "**/*.ts")
3. 對每個檔案執行 read_text_file()
4. 在檔案開頭插入 copyright header
5. 使用 write_file() 寫回

結果：30 個檔案自動加上 header

可用工具詳解

1. read_text_file(path: string) 📖

以文字讀取檔案內容；可選的 head 或 tail 只回傳前或後 N 行。read_file 仍可使用，但已是棄用的別名。

2. write_file(path: string, content: string) ✍️

寫入或覆蓋檔案。

⚠️ 注意：會覆蓋現有檔案，請謹慎使用。

3. edit_file(path: string, edits: Edit[]) ✂️

行級編輯，支援搜尋與替換。

4. list_directory(path: string) 📂

列出目錄內容。

5. create_directory(path: string) 🆕

建立新目錄（支援巢狀建立）。

6. move_file(source: string, destination: string) 🔀

移動或重新命名檔案。

7. search_files(path: string, pattern: string, excludePatterns?: string[]) 🔍

從 path 開始，以 glob 模式遞迴搜尋檔案。

支援的 glob 模式：

• *.ts - 起始目錄下的所有 TS 檔案
• **/*.ts - 所有子目錄下的 TS 檔案
• src/**/*.{ts,tsx} - src 下的 TS 和 TSX 檔案

8. get_file_info(path: string) ℹ️

取得檔案元資料。

安全性最佳實踐

✅ 推薦做法

1. 最小權限原則
2. 敏感資料保護
3. 使用唯讀模式
4. 定期審查權限

❌ 避免做法

1. 授權根目錄 / - 永遠不要這樣做
2. 授權系統目錄 /etc, /usr, /System - 危險
3. 授權 home 目錄 ~ - 範圍太大
4. 硬編碼絕對路徑 - 使用相對路徑或環境變數

與其他 MCP 服務器協同

Filesystem MCP 可與其他 MCP 服務器完美協同：

1. Filesystem + Memory MCP

2. Filesystem + Context7 MCP

3. Filesystem + Sequential Thinking MCP

結論

Filesystem MCP 是 AI 助手操作檔案系統的安全橋樑。它在提供強大檔案操作能力的同時，透過嚴格的權限控制確保系統安全。

適合你嗎？

使用場景	推薦度
批量檔案重構	⭐⭐⭐⭐⭐
專案結構分析	⭐⭐⭐⭐⭐
自動化檔案處理	⭐⭐⭐⭐⭐
多專案管理	⭐⭐⭐⭐
敏感資料處理	⭐⭐ (需謹慎設定權限)

立即開始

1. 安裝：claude mcp add --scope project filesystem -- npx -y @modelcontextprotocol/server-filesystem "$(pwd)"
2. 授權專案目錄
3. 開始享受 AI 驅動的檔案操作

延伸閱讀

• Filesystem MCP GitHub Repository
• Filesystem MCP npm Package
• Model Context Protocol Official Documentation