MCP File Tools

🚀 MCP文件工具

MCP文件工具是一個支持非UTF - 8編碼的文件操作服務器。它能夠自動檢測並轉換22種編碼（包括西里爾文、Windows - 125x、ISO - 8859、KOI8、UTF - 16等），讓AI助手在讀寫舊文件時不會破壞數據。該工具非常適合Delphi/Pascal項目、舊的VB6應用程序、老的PHP/HTML網站以及包含非UTF - 8文本的配置文件。

🚀 快速開始

安裝完成後，你只需向Claude提出相關需求，例如：

• "列出此目錄下所有的.pas文件"
• "讀取config.ini並檢測其編碼"
• "顯示所有支持的編碼"
• "使用CP1251編碼讀取MainForm.dfm"

安全說明：服務器僅訪問你明確允許的目錄：

• 自動方式：Claude Desktop/Code會自動提供工作區目錄
• 手動方式：在配置文件的args: ["/path/to/project"]中指定目錄

✨ 主要特性

• 提供19種文件操作工具，支持自動編碼轉換。
• 支持22種編碼，涵蓋Unicode、西里爾文、西歐、中歐、希臘、土耳其等多種編碼類型。
• 所有操作都限制在允許的目錄內，保障安全性。

📦 安裝指南

MCP註冊表

該服務器已列入官方MCP註冊表，方便發現。

Windows x64

注意：請在PowerShell中運行以下命令，而非CMD。

# 下載
mkdir -Force "$env:LOCALAPPDATA\Programs\mcp-file-tools"
iwr "https://github.com/dimitar-grigorov/mcp-file-tools/releases/latest/download/mcp-file-tools_windows_amd64.exe" -OutFile "$env:LOCALAPPDATA\Programs\mcp-file-tools\mcp-file-tools.exe"
# 使用Claude Code + VSCode安裝（允許訪問D:\Projects）
claude mcp add --scope user file-tools -- "$env:LOCALAPPDATA\Programs\mcp-file-tools\mcp-file-tools.exe" "D:\Projects"

Linux x64

# 下載
mkdir -p ~/.local/bin
curl -L "https://github.com/dimitar-grigorov/mcp-file-tools/releases/latest/download/mcp-file-tools_linux_amd64" -o ~/.local/bin/mcp-file-tools
chmod +x ~/.local/bin/mcp-file-tools
# 使用Claude Code + VSCode安裝（允許訪問~/Projects）
claude mcp add --scope user file-tools -- ~/.local/bin/mcp-file-tools ~/Projects

macOS ARM64

# 下載
mkdir -p ~/.local/bin
curl -L "https://github.com/dimitar-grigorov/mcp-file-tools/releases/latest/download/mcp-file-tools_darwin_arm64" -o ~/.local/bin/mcp-file-tools
chmod +x ~/.local/bin/mcp-file-tools
# 使用Claude Code + VSCode安裝（允許訪問~/Projects）
claude mcp add --scope user file-tools -- ~/.local/bin/mcp-file-tools ~/Projects

Go Install（所有平臺）

# 使用Go安裝（需要Go 1.23+）
go install github.com/dimitar-grigorov/mcp-file-tools/cmd/mcp-file-tools@latest
# 添加到Claude Code + VSCode（Linux/macOS）
claude mcp add --scope user file-tools -- $(go env GOPATH)/bin/mcp-file-tools ~/Projects

# 添加到Claude Code + VSCode（Windows PowerShell）
claude mcp add --scope user file-tools -- "$(go env GOPATH)\bin\mcp-file-tools.exe" "D:\Projects"

其他客戶端

對於Claude Desktop、VSCode或Cursor，在配置中使用下載的二進制文件路徑：

Claude Desktop（Windows上的%APPDATA%\Claude\claude_desktop_config.json，macOS上的~/Library/Application Support/Claude/claude_desktop_config.json）：

Windows:

{
  "mcpServers": {
    "file-tools": {
      "command": "C:\\Users\\YOUR_NAME\\AppData\\Local\\Programs\\mcp-file-tools\\mcp-file-tools.exe",
      "args": ["D:\\Projects", "C:\\Users\\YOUR_NAME\\Documents"]
    }
  }
}

macOS / Linux:

{
  "mcpServers": {
    "file-tools": {
      "command": "/Users/YOUR_NAME/.local/bin/mcp-file-tools",
      "args": ["/Users/YOUR_NAME/Projects", "/Users/YOUR_NAME/Documents"]
    }
  }
}

args數組指定服務器可以訪問的允許目錄，你可以根據需要添加多個目錄。

VSCode / Cursor（Claude Code擴展） 如果你已經在上述安裝步驟中運行了claude mcp add --scope user，則服務器已在VSCode中可用，無需額外配置。

若要單獨為VSCode配置：

claude mcp add --scope user file-tools -- "%LOCALAPPDATA%\Programs\mcp-file-tools\mcp-file-tools.exe" "D:\Projects"

或者，通過在項目根目錄添加.mcp.json創建項目級配置：

{
  "mcpServers": {
    "file-tools": {
      "type": "stdio",
      "command": "C:\\Users\\YOUR_NAME\\AppData\\Local\\Programs\\mcp-file-tools\\mcp-file-tools.exe",
      "args": ["D:\\Projects", "D:\\Other\\Directory"]
    }
  }
}

注意：type: "stdio"字段是必需的。args數組指定允許的目錄，VSCode擴展不會自動添加工作區目錄，因此你必須列出所有要訪問的目錄。若要稍後添加更多目錄，請重新運行claude mcp add命令並列出所有目錄（它會覆蓋之前的配置）。

自動批准所有工具（Claude Code）

若要跳過所有文件工具命令的權限提示，可在項目根目錄創建.claude/settings.local.json：

{
  "permissions": {
    "allow": [
      "Bash(ls *)",
      "Bash(grep *)",
      "Bash(sort *)",
      "Bash(wc *)",
      "Bash(find *)",
      "Bash(echo *)",
      "Grep",
      "Glob",
      "WebSearch",
      "mcp__file-tools__read_text_file",
      "mcp__file-tools__read_multiple_files",
      "mcp__file-tools__write_file",
      "mcp__file-tools__edit_file",
      "mcp__file-tools__copy_file",
      "mcp__file-tools__list_directory",
      "mcp__file-tools__tree",
      "mcp__file-tools__directory_tree",
      "mcp__file-tools__search_files",
      "mcp__file-tools__grep_text_files",
      "mcp__file-tools__detect_encoding",
      "mcp__file-tools__convert_encoding",
      "mcp__file-tools__detect_line_endings",
      "mcp__file-tools__list_encodings",
      "mcp__file-tools__get_file_info",
      "mcp__file-tools__create_directory",
      "mcp__file-tools__list_allowed_directories"
    ]
  }
}

這將自動批准安全的只讀和編輯文件工具操作，以及常見的shell命令和網絡搜索。破壞性操作（delete_file、move_file）和WebFetch有意排除在外，Claude在使用它們之前會詢問。你可以根據需要進行調整。

驗證與卸載

# 檢查服務器是否已配置
claude mcp list

# 移除服務器
claude mcp remove file-tools

💻 使用示例

基礎用法

例如，你可以向Claude提出如下需求：

User: 讀取config.ini並將標題更改為 "Настройки"
Assistant: [使用cp1251編碼讀取文件] → [以UTF - 8格式修改內容] → [使用cp1251編碼寫入文件]

這樣可以保留原始編碼，確保文件與舊工具兼容。

📚 詳細文檔

工具列表

提供19種用於文件操作的工具，支持自動編碼轉換：

• - 自動檢測並轉換編碼後讀取文件
• - 併發讀取多個文件，支持編碼轉換
• - 以特定編碼寫入文件
• - 基於行的編輯，提供差異預覽和靈活的空格匹配
• - 將文件複製到新位置
• - 刪除文件
• - 按模式過濾瀏覽目錄
• - 緊湊的縮進樹視圖（比JSON少85%的令牌）
• - 以JSON格式獲取遞歸樹視圖（已棄用，使用tree）
• - 遞歸搜索匹配通配符模式的文件
• - 在文件內容中進行正則搜索，支持編碼轉換
• - 自動檢測文件編碼並給出置信度分數
• - 在不同編碼之間轉換文件
• - 檢測行結束樣式（CRLF/LF/混合）
• - 顯示所有支持的編碼
• - 獲取文件/目錄元數據
• - 遞歸創建目錄（類似於mkdir -p）
• - 移動或重命名文件和目錄
• - 顯示可訪問的目錄

支持的編碼（共22種）

• Unicode：UTF - 8、UTF - 16 LE、UTF - 16 BE（支持UTF - 16和UTF - 32的BOM檢測）
• 西里爾文：Windows - 1251、KOI8 - R、KOI8 - U、CP866、ISO - 8859 - 5
• 西歐：Windows - 1252、ISO - 8859 - 1、ISO - 8859 - 15
• 中歐：Windows - 1250、ISO - 8859 - 2
• 希臘：Windows - 1253、ISO - 8859 - 7
• 土耳其：Windows - 1254、ISO - 8859 - 9
• 其他：希伯來文（1255）、阿拉伯文（1256）、波羅的海文（1257）、越南文（1258）、泰文（874）

詳細參數和示例請參考TOOLS.md。

配置說明

服務器可以通過環境變量進行配置：

若要覆蓋默認值，可在配置中設置環境變量（以Claude Desktop為例）：

{
  "mcpServers": {
    "file-tools": {
      "command": "C:\\Users\\YOUR_NAME\\AppData\\Local\\Programs\\mcp-file-tools\\mcp-file-tools.exe",
      "args": ["D:\\Projects"],
      "env": {
        "MCP_DEFAULT_ENCODING": "utf-8"
      }
    }
  }
}

🔧 技術細節

開發環境

前提條件：Go 1.23+

# 運行測試
go test ./...

# 構建
go build -o mcp-file-tools ./cmd/mcp-file-tools

使用MCP Inspector進行調試

MCP Inspector提供了一個Web UI，用於測試MCP服務器。

前提條件：Node.js v18+

# 運行並指定允許的目錄（必需）
npx @modelcontextprotocol/inspector go run ./cmd/mcp-file-tools -- /path/to/allowed/dir

# 或者使用已構建的二進制文件
npx @modelcontextprotocol/inspector ./mcp-file-tools.exe C:\Projects

運行後會打開一個瀏覽器，你可以在其中查看工具、使用自定義參數調用工具並檢查響應。

手動調試

運行服務器並指定允許的目錄，然後通過stdin發送JSON - RPC命令：

# 指定允許的目錄
go run ./cmd/mcp-file-tools /path/to/project

示例命令（粘貼到終端）：

{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_directory","arguments":{"path":"/path/to/project","pattern":"*.go"}}}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"read_text_file","arguments":{"path":"/path/to/project/main.pas","encoding":"cp1251"}}}
{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"detect_encoding","arguments":{"path":"/path/to/project/file.txt"}}}

📄 許可證

本項目採用GPL - 3.0許可證，詳情請參閱LICENSE。