MCP Filesystem

🚀 MCP文件系統服務器

MCP文件系統服務器是一個強大的模型上下文協議（MCP）服務器，專為文件系統操作而設計，尤其適用於與大型文件和文件系統進行智能交互。它通過智能上下文管理，為文件和目錄提供安全訪問，在處理大量數據時可最大程度提高效率。

🚀 快速開始

1. 克隆並設置

首先，若尚未安裝uv，請進行安裝：

# 使用官方安裝程序安裝uv
curl -fsSL https://raw.githubusercontent.com/astral-sh/uv/main/install.sh | bash

# 或者使用pipx安裝
pipx install uv

然後克隆倉庫並安裝依賴項：

# 克隆倉庫
git clone https://github.com/safurrier/mcp-filesystem.git
cd mcp-filesystem

# 使用uv安裝依賴項
uv pip sync requirements.txt requirements-dev.txt

2. 獲取絕對路徑

你需要獲取倉庫位置以及想要訪問的任何目錄的絕對路徑：

# 獲取倉庫的絕對路徑
REPO_PATH=$(pwd)
echo "倉庫路徑: $REPO_PATH"

# 獲取想要訪問的目錄的絕對路徑
realpath ~/Documents
realpath ~/Downloads
# 或者在沒有realpath的系統上：
echo "$(cd ~/Documents && pwd)"

3. 配置Claude桌面版

打開Claude桌面版配置文件：

• 在macOS上：~/Library/Application\ Support/Claude/claude_desktop_config.json
• 在Windows上：%APPDATA%/Claude/claude_desktop_config.json

添加以下配置（替換為你實際的路徑）：

{
  "mcpServers": {
    "mcp-filesystem": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-filesystem",
        "run",
        "run_server.py",
        "/absolute/path/to/dir1",
        "/absolute/path/to/dir2"
      ]
    }
  }
}

⚠️ 重要提示

所有路徑必須是絕對路徑（從根目錄開始的完整路徑）。請使用realpath或pwd確保你擁有正確的絕對路徑。

4. 重啟Claude桌面版

保存配置後，重啟Claude桌面版以使更改生效。

✨ 主要特性

智能上下文管理

• 高效處理大型文件和文件系統：
  • 部分讀取，僅關注相關內容。
  • 精確的上下文控制，可準確找到所需內容。
  • 支持分頁的高效令牌搜索結果。
  • 多文件操作，減少請求開銷。

智能文件操作

• 支持行定位讀取，可配置上下文窗口。
• 高級編輯功能，具備內容驗證，防止衝突。
• 細粒度搜索功能，超越標準grep。
• 支持相對行引用，便於精確文件操作。

安全文件訪問

僅允許在明確允許的目錄內進行操作。

全面操作

• 標準操作（讀取、寫入、列出、移動、刪除）。
• 增強操作（樹形可視化、查找重複項等）。
• 集成grep的高級搜索（可用時使用ripgrep）：
  • 上下文控制（如grep的-A/-B/-C選項）。
  • 大結果集的結果分頁。
• 支持內容驗證和相對行號的行定位操作。

性能優化

• 高效處理大型文件和目錄。
• 集成ripgrep，實現快速搜索。
• 行定位操作，避免加載整個文件。

全面測試

採用行為驅動方法，擁有75多個測試用例。

跨平臺支持

可在Windows、macOS和Linux上運行。

📦 安裝指南

克隆並設置

首先，若尚未安裝uv，請進行安裝：

# 使用官方安裝程序安裝uv
curl -fsSL https://raw.githubusercontent.com/astral-sh/uv/main/install.sh | bash

# 或者使用pipx安裝
pipx install uv

然後克隆倉庫並安裝依賴項：

# 克隆倉庫
git clone https://github.com/safurrier/mcp-filesystem.git
cd mcp-filesystem

# 使用uv安裝依賴項
uv pip sync requirements.txt requirements-dev.txt

💻 使用示例

基礎用法

查看服務器日誌

你可以在Claude桌面版中監控服務器日誌：

# 在macOS上
tail -n 20 -f ~/Library/Logs/Claude/mcp-server-mcp-filesystem.log

# 在Windows（PowerShell）上
Get-Content -Path "$env:APPDATA\Claude\Logs\mcp-server-mcp-filesystem.log" -Tail 20 -Wait

運行服務器

運行服務器並訪問特定目錄：

# 使用uv（推薦）
uv run run_server.py /path/to/dir1 /path/to/dir2

# 或者使用標準Python
python run_server.py /path/to/dir1 /path/to/dir2

# 實際路徑示例
uv run run_server.py /Users/username/Documents /Users/username/Downloads

選項

• --transport 或 -t：傳輸協議（stdio 或 sse，默認：stdio）
• --port 或 -p：SSE傳輸端口（默認：8000）
• --debug 或 -d：啟用調試日誌
• --version 或 -v：顯示版本信息

使用MCP檢查器

使用MCP檢查器進行交互式測試和調試：

# 基本用法
npx @modelcontextprotocol/inspector uv run run_server.py /path/to/directory

# 使用SSE傳輸
npx @modelcontextprotocol/inspector uv run run_server.py /path/to/directory --transport sse --port 8080

# 輸出調試信息
npx @modelcontextprotocol/inspector uv run run_server.py /path/to/directory --debug

高級用法

讀取文件行

Tool: read_file_lines
Arguments: {
  "path": "/path/to/file.txt",
  "offset": 99,        # 基於0的索引（第100行）
  "limit": 51,         # 讀取51行
  "encoding": "utf-8"  # 可選編碼
}

使用grep搜索內容

Tool: grep_files
Arguments: {
  "path": "/path/to/search",
  "pattern": "function\\s+\\w+\\(",
  "is_regex": true,
  "context_before": 2,       # 顯示每個匹配項前的2行（如grep的 -A 選項）
  "context_after": 5,        # 顯示每個匹配項後的5行（如grep的 -B 選項）
  "include_patterns": ["*.js", "*.ts"],
  "results_offset": 0,       # 從第一個匹配項開始
  "results_limit": 20        # 最多顯示20個匹配項
}

行定位編輯

Tool: edit_file_at_line
Arguments: {
  "path": "/path/to/file.txt",
  "line_edits": [
    {
      "line_number": 15,
      "action": "replace",
      "content": "This is the new content for line 15\n",
      "expected_content": "Original content of line 15\n" # 編輯前驗證內容
    },
    {
      "line_number": 20,
      "action": "delete"
    }
  ],
  "offset": 0,                           # 從該偏移量開始考慮行
  "relative_line_numbers": false,        # 行號是否相對於偏移量
  "abort_on_verification_failure": true, # 驗證失敗時停止
  "dry_run": true                        # 預覽更改而不應用
}

查找重複文件

Tool: find_duplicate_files
Arguments: {
  "path": "/path/to/search",
  "recursive": true,
  "min_size": 1024,
  "format": "text"
}

📚 詳細文檔

可用工具

基本文件操作

• read_file：讀取文件的完整內容。
• read_multiple_files：同時讀取多個文件。
• write_file：創建新文件或覆蓋現有文件。
• create_directory：創建新目錄或確保目錄存在。
• list_directory：獲取文件和目錄的詳細列表。
• move_file：移動或重命名文件和目錄。
• get_file_info：檢索文件或目錄的詳細元數據。
• list_allowed_directories：列出服務器允許訪問的目錄。

行定位操作

• read_file_lines：使用偏移量/限制參數讀取特定行範圍。
• edit_file_at_line：具備內容驗證和相對行號的精確編輯：
  • 支持內容驗證，防止編輯過時內容。
  • 支持相對行號，便於區域編輯。
  • 支持多種編輯操作（替換、插入前、插入後、刪除）。
• head_file：讀取文本文件的前N行。
• tail_file：讀取文本文件的後N行。

高級搜索

• grep_files：在文件中搜索模式，具備強大選項：
  • 集成ripgrep以提高性能（有Python後備方案）。
  • 細粒度上下文控制（如grep的-A/-B/-C選項）。
  • 大搜索結果的結果分頁。
  • 支持正則表達式，可設置大小寫敏感和全字匹配選項。
• search_files：搜索匹配模式的文件，支持內容搜索。
• directory_tree：獲取文件和目錄的遞歸樹視圖。

分析和報告

• calculate_directory_size：計算目錄的總大小。
• find_duplicate_files：通過比較內容查找重複文件。
• compare_files：比較兩個文本文件並顯示差異。
• find_large_files：查找大於指定大小的文件。
• find_empty_directories：查找空目錄。

處理大型文件和文件系統的高效工作流程

智能上下文發現

• 使用grep_files，通過精確的上下文控制找到所需內容。
• 對匹配項前後的上下文行進行細粒度控制，避免令牌浪費。
• 高效分頁處理大結果集，避免超出令牌限制。
• 集成ripgrep，可處理包含數百萬個文件和行的大型文件系統。

目標讀取

• 使用read_file_lines，通過偏移量/限制僅檢查相關部分。
• 基於0的索引，使用簡單的偏移量/限制參數精確檢索內容。
• 精確控制讀取的行數，提高令牌效率。
• 同時讀取多個文件，減少往返次數。

精確編輯

• 使用edit_file_at_line進行目標編輯，具備內容驗證。
• 編輯前驗證內容未更改，防止衝突。
• 使用相對行號進行復雜文件的區域編輯。
• 一次操作支持多種編輯操作，處理複雜更改。
• 支持預運行功能，預覽更改後再應用。

高級分析

• 使用find_duplicate_files和compare_files等專業工具。
• 使用directory_tree生成目錄樹，便於快速導航。
• 使用find_large_files和find_empty_directories識別問題區域。

與標準文件系統MCP服務器相比的優勢

令牌效率

• 智能行定位操作避免將整個文件加載到上下文中。
• 大結果集的分頁控制，防止上下文溢出。
• 精確的grep，支持上下文控制（不僅是全文件搜索）。
• 多文件讀取減少往返請求。

智能編輯

• 內容驗證，防止編輯衝突。
• 行定位編輯，無需加載整個文件。
• 支持相對行號，便於區域編輯。
• 支持預運行功能，預覽更改後再應用。

高級搜索

• 集成ripgrep，提高大型文件系統性能。
• 支持上下文感知結果（不僅是匹配項）。
• 對返回內容進行細粒度控制。
• 基於模式的文件查找，支持排除選項。

附加實用工具

• 文件比較和去重。
• 目錄大小計算和分析。
• 空目錄識別。
• 基於樹的目錄可視化。

安全重點

• 強大的路徑驗證和沙箱機制。
• 防止路徑遍歷攻擊。
• 符號鏈接驗證和安全保護。
• 詳細的錯誤報告，不暴露敏感信息。

已知問題和限制

• 路徑解析：為獲得最一致的結果，請始終使用絕對路徑。相對路徑可能相對於服務器的工作目錄而非允許的目錄進行解釋。
• 性能：對於大型目錄，find_duplicate_files等操作或遞歸搜索可能需要較長時間才能完成。
• 權限處理：服務器以運行它的用戶的相同權限運行。請確保服務器對需要訪問的目錄具有適當的權限。

安全

服務器實施嚴格的路徑驗證，防止訪問允許目錄之外的內容：

• 僅允許在明確允許的目錄內進行操作。
• 防止路徑遍歷攻擊。
• 驗證符號鏈接，確保其不指向允許目錄之外。
• 返回有意義的錯誤消息，不暴露敏感信息。

性能考慮

為獲得最佳grep功能性能：

• 安裝ripgrep (rg)。
• 服務器在可用時會自動使用ripgrep，並提供Python後備方案。

🔧 技術細節

該服務器使用FastMCP SDK構建，以更好地符合當前MCP最佳實踐。它採用高效的組件緩存系統和直接裝飾器模式。

📄 許可證

MIT許可證