MCP File Tools

MCP文件工具

克劳德看到 Настройки --不是 ???? 或 Íàñòðîéêè.

MCP服务器，用于支持非UTF-8编码的文件操作。自动检测和转换22种编码（西里尔文、Windows-125x、ISO-8859、KOI8、UTF-16），这样AI助手就可以在不损坏数据的情况下读写旧文件。

非常适合： Delphi/Pascal项目、遗留的VB6应用程序、旧的PHP/HTML网站、非UTF-8文本的配置文件。

它的作用

提供21个工具，用于自动编码转换的文件操作：

• read_text_file -读取具有编码自动检测和转换功能的文件
• read_multiple_files -使用编码支持同时读取多个文件
• write_file -以特定编码写入文件
• edit_file -基于行的编辑，具有差异预览和空白灵活匹配功能
• copy_file -将文件复制到新位置
• delete_file -删除文件
• list_directory -使用模式过滤浏览目录
• tree -紧凑的缩进树视图（比JSON少85%的标记）
• directory_tree -以JSON格式获取递归树视图（已弃用，请使用 tree)
• search_files -递归搜索与glob模式匹配的文件
• grep_text_files -支持编码的文件内容中的正则表达式搜索
• detect_encoding -使用置信度评分自动检测文件编码
• convert_encoding -在编码之间转换文件
• detect_line_endings -检测行尾样式（CRLF/LF/混合）
• change_line_endings -将行尾转换为LF或CRLF
• manage_bom -检测、剥离或添加Unicode BOM
• list_encodings -显示所有支持的编码
• get_file_info -获取文件/目录元数据
• create_directory -递归创建目录（mkdir-p）
• move_file -移动或重命名文件和目录
• list_allowed_directories -显示可访问的目录

支持的编码（共22种）：

• Unicode： UTF-8、UTF-16LE、UTF-16BE（带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 详细参数和示例。

安全： 所有操作仅限于允许的目录。

安装

MCP注册表

此服务器列在 MCP官方登记处 为了发现。

Windows x64

注： 在中运行这些命令 PowerShell不在CMD中。

# Download
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"
# Install with Claude Code + VSCode (allows access to D:\Projects)
claude mcp add --scope user file-tools -- "$env:LOCALAPPDATA\Programs\mcp-file-tools\mcp-file-tools.exe" "D:\Projects"

Linux x64

# Download
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
# Install with Claude Code + VSCode (allows access to ~/Projects)
claude mcp add --scope user file-tools -- ~/.local/bin/mcp-file-tools ~/Projects

macOS ARM64

# Download
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
# Install with Claude Code + VSCode (allows access to ~/Projects)
claude mcp add --scope user file-tools -- ~/.local/bin/mcp-file-tools ~/Projects

去安装（所有平台）

# Install with Go (requires Go 1.23+)
go install github.com/dimitar-grigorov/mcp-file-tools/cmd/mcp-file-tools@latest
# Add to Claude Code + VSCode (Linux/macOS)
claude mcp add --scope user file-tools -- $(go env GOPATH)/bin/mcp-file-tools ~/Projects

# Add to 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，请在配置中使用下载的二进制路径：

克劳德桌面版 (%APPDATA%\Claude\claude_desktop_config.json 在Windows上， ~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

窗户：

{
  "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 array指定服务器可以访问的允许目录。根据需要添加任意多的目录。

VSCode/Cursor（克劳德代码扩展）

如果你已经跑了 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 array指定了允许的目录——VSCode扩展不会自动添加工作区目录，因此您必须列出要访问的所有目录。若要稍后添加更多目录，请重新运行 claude mcp add 列出所有目录的命令（它会覆盖之前的配置）。

OpenAI Codex命令行界面

Codex没有 mcp add 命令--您需要编辑 ~/.codex/config.toml 手动。

Windows（PowerShell）：

# Download
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"

然后添加到 ~/.codex/config.toml:

[mcp_servers.file-tools]
command = "C:\\Users\\YOUR_NAME\\AppData\\Local\\Programs\\mcp-file-tools\\mcp-file-tools.exe"
args = ["D:\\Projects"]

自动批准所有工具（Claude代码）

要跳过所有文件工具命令的权限提示，请创建 .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__change_line_endings",
      "mcp__file-tools__manage_bom",
      "mcp__file-tools__list_encodings",
      "mcp__file-tools__get_file_info",
      "mcp__file-tools__create_directory",
      "mcp__file-tools__list_allowed_directories",
      "mcp__file-tools__check_for_updates"
    ]
  }
}

此自动批准安全的只读和编辑文件工具操作以及常见的shell命令和web搜索。破坏性行动(delete_file, move_file)以及 WebFetch 被故意排除在外——克劳德在使用它们之前会问。根据您的需求进行调整。

更新

服务器会自动检查更新，并在有新版本可用时通过工具响应通知您。要更新，请执行以下操作：

1. 关闭所有Claude Code会话（运行时二进制文件被锁定）
2. 重新下载二进制文件：

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"

要禁用更新检查，请设置环境变量 MCP_NO_UPDATE_CHECK=1.

验证和卸载

# Check if the server is configured
claude mcp list

# Remove the server
claude mcp remove file-tools

如何使用

安装后，只需询问Claude：

• “列出此目录中的所有.pas文件”
• “读取config.ini并检测其编码”
• “显示所有支持的编码”
• “使用CP1251编码读取MainForm.dfm”

安全： 服务器只访问您明确允许的目录：

• 自动： Claude Desktop/Code自动提供工作区目录
• 手册： 在配置中指定目录 args: ["/path/to/project"]

配置

服务器可以通过环境变量进行配置：

要覆盖，请在配置中设置环境变量（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"
      }
    }
  }
}

用例

遗留代码库

许多遗留项目使用非UTF-8编码，人工智能助手无法原生处理：

• Delphi/Pascal （Windows-1251）：带有西里尔字母UI文本的源文件
• Visual Basic 6 （Windows-1252）：带有西欧字符的表单和配置文件
• 传统PHP/HTML （CP1251，ISO-8859-1）：具有本地化内容的Web应用程序
• 旧配置文件 （各种）：INI、属性、具有传统编码的注册表文件

它是如何工作的：

User: Read config.ini and change the title to "Настройки"
Assistant: [read_text_file with cp1251] → [modify UTF-8] → [write_file with cp1251]

原始编码得以保留，文件仍与旧版工具兼容。

发展

先决条件： 转到1.23+

# Run tests
go test ./...

# Build
go build -o mcp-file-tools ./cmd/mcp-file-tools

使用MCP检查器进行调试

MCP检查员 提供了一个用于测试MCP服务器的web UI。

先决条件： Node.js v18+

# Run with allowed directory (required)
npx @modelcontextprotocol/inspector go run ./cmd/mcp-file-tools -- /path/to/allowed/dir

# Or with built binary
npx @modelcontextprotocol/inspector ./mcp-file-tools.exe C:\Projects

打开一个浏览器，您可以在其中查看工具，使用自定义参数调用它们，并检查响应。

手动调试

使用允许的目录运行服务器，并通过stdin发送JSON-RPC命令：

# Specify allowed directory
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-见 许可证