Mcp File Tools

MCP File Tools

Claude 看到的是 Настройки —— 而不是 ???? 或 Íàñòðîéêè。

用于对非 UTF-8 文本进行文件操作的 MCP 服务。它根据文件的字节而非扩展名来检测编码，将 UTF-8 交给模型，并以原始编码写回 —— BOM 和 CRLF/LF 保持不变，与拥有该文件的任何旧式工具仍保持字节兼容。

• 45 种编码，可读可写 —— 西里尔字母（CP1251、KOI8-R/U、CP866/855）、Windows-125x、ISO-8859-x、DOS 代码页、MacRoman、UTF-16/UTF-32、CJK（GBK、Big5、Shift_JIS、EUC-JP/KR）（完整列表）
• 整套工具均支持编码感知 —— edit_file、grep_text_files 和 search_files 以相同方式解码，而不仅仅是读取和写入
• 检测结果可检查 —— detect_encoding 会报告字符集、置信度分数以及任何 BOM，因此乱码文本变得可诊断
• BOM 和行尾是一等公民 —— 包括在 UTF-16 上，此时天真的字节级重写会损坏文件
• 沙箱化 —— 每条路径（包括符号链接和联接目标）都会对照你允许的目录进行检查

专为以下场景打造： 带有西里尔字母界面文本的 Delphi/Pascal 单元、VB6 窗体、含本地化内容的旧式 PHP/HTML，以及无法从文件名判断编码的 INI 或数据文件。

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

欢迎 PR，合并迅速 —— 无需 CLA，不做风格审查，一行修复也算数。为了修复某个问题而 fork 了本仓库？请把它发回来。

安装

Claude Code 插件（推荐）

claude plugin marketplace add dimitar-grigorov/mcp-file-tools
claude plugin install mcp-file-tools

在会话中执行：/plugin marketplace add … 和 /plugin install …。

需要 PATH 中有 Node.js 18+。 启动器是一个 Node 脚本，而 Claude Code 不捆绑 Node；没有它，/mcp 会将服务显示为未连接。

首次启动会下载适用于你操作系统的固定版本二进制文件，验证其 SHA-256 并缓存。它的作用范围限于你打开的文件夹，因此无需配置。对于工作区之外的目录，或没有 Node 的机器，请使用手动安装。

从手动安装迁移

claude mcp list                                              # find the old file-tools entry
claude mcp remove file-tools
claude plugin marketplace add dimitar-grigorov/mcp-file-tools
claude plugin install mcp-file-tools
# Old binary, once /mcp shows the plugin connected:
#   Windows      Remove-Item "$env:LOCALAPPDATA\Programs\mcp-file-tools\mcp-file-tools.exe"
#   Linux/macOS  rm ~/.local/bin/mcp-file-tools

工具名称也会变化：mcp__file-tools__* 变为 mcp__plugin_mcp-file-tools_file-tools__*，因此请更新你的权限规则，参见自动批准工具。

更新插件

claude plugin marketplace update mcp-file-tools
claude plugin update mcp-file-tools@mcp-file-tools

请使用完整的 plugin@marketplace ID，而不是裸名称，或在 /plugin → Marketplaces 中开启自动更新。

注册表与目录

本服务已收录于官方 MCP Registry，可供任何 MCP 客户端发现，并在 Glama 上建立索引，后者在许可证、质量和维护方面给它评分为 A。

手动安装（其他 MCP 客户端，或在工作区之外访问）

下载适用于你平台的二进制文件，然后将其与可访问的目录一起注册。

平台	发布资源	建议路径
Windows x64	mcp-file-tools_windows_amd64.exe	%LOCALAPPDATA%\Programs\mcp-file-tools\mcp-file-tools.exe
Linux x64	mcp-file-tools_linux_amd64	~/.local/bin/mcp-file-tools
macOS ARM64	mcp-file-tools_darwin_arm64	~/.local/bin/mcp-file-tools

Windows（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 mcp add --scope user file-tools -- "$env:LOCALAPPDATA\Programs\mcp-file-tools\mcp-file-tools.exe" "C:\Projects"

Linux / macOS（将表中的资源名称替换为你平台的名称）：

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 mcp add --scope user file-tools -- ~/.local/bin/mcp-file-tools ~/Projects

Go 安装（所有平台）

# Requires Go 1.27+
go install github.com/dimitar-grigorov/mcp-file-tools/v4/cmd/mcp-file-tools@latest
# Linux / macOS
claude mcp add --scope user file-tools -- $(go env GOPATH)/bin/mcp-file-tools ~/Projects

# Windows PowerShell
claude mcp add --scope user file-tools -- "$(go env GOPATH)\bin\mcp-file-tools.exe" "C:\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 -- "$env:LOCALAPPDATA\Programs\mcp-file-tools\mcp-file-tools.exe" "C:\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"。VSCode 扩展不会自行添加工作区 目录，因此 args 必须列出所有你想要访问的目录。稍后添加一个 目录意味着要用完整列表重新运行 claude mcp add — 它会覆盖之前的 配置，而不是追加。

OpenAI Codex CLI

Codex 接受直接的 MCP 命令，因此无需手动编辑 TOML。

Windows（PowerShell）：

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 mcp add file-tools -- "$env:LOCALAPPDATA\Programs\mcp-file-tools\mcp-file-tools.exe" "C:\Projects"

运行 codex mcp list 进行验证，然后启动新的 Codex 会话。添加更多目录 参数以授予当前项目之外的访问权限。

自动批准工具（Claude Code）

要跳过权限提示，请在项目根目录的 .claude/settings.local.json 中添加：

{ "permissions": { "allow": ["mcp__plugin_mcp-file-tools_file-tools__*"] } }

该前缀是插件安装；手动注册为 file-tools 的则是 mcp__file-tools__*，而前缀错误的规则不会匹配任何内容，并且会 静默失败。这些规则影响哪些模式，以及将 delete_file / move_file 保留在 提示之后，详见 docs/extra.md。

更新

服务会自动检查更新，并在有 新版本可用时通过工具响应通知你；该通知包含适用于你安装方式的步骤。插件安装 通过更新插件进行更新 — 在那里重新下载的二进制文件会被 忽略。

对于手动安装，在现有二进制文件上重新下载即可 — 注册 无需重复：

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 which file-tools server is connected (plugin or manual)
claude mcp list

# Remove a manual install
claude mcp remove file-tools

# Remove the plugin
claude plugin uninstall mcp-file-tools

如何使用

安装完成后，只需询问 Claude：

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

安全性： 服务只能访问你允许的目录。它首先从 args: ["/path/to/project"] 获取，然后从 MCP_FILE_TOOLS_ALLOWED_DIRS 获取，若两者均无， 则从启动时所在的目录获取 — 当客户端在该目录启动时，即为工作区。 仍使用 MCP roots 协议的客户端会在此基础上添加其 roots。驱动器根目录或 你的主目录绝不会通过最后这个回退方案被授予；请改为显式指定。路径 在检查之前会被解析，因此指向外部的符号链接或 Windows junction 会被 拒绝，而不是被跟随。

工具

共有 20 个工具——每个处理文本内容的工具都支持编码：

• read_text_file - 读取文件，自动检测并转换编码
• read_multiple_files - 并发读取多个文件，并支持编码
• write_file - 以指定编码写入文件
• edit_file - 按行编辑，提供差异预览，并支持灵活匹配空白字符
• copy_file - 将文件复制到新位置
• delete_file - 删除文件
• list_directory - 浏览目录，并按模式筛选
• tree - 以紧凑的缩进树状视图显示内容，还可选择为每个文件标注编码
• search_files - 递归搜索与 glob 模式匹配的文件
• grep_text_files - 在文件内容中进行正则表达式搜索，并支持编码
• detect_encoding - 自动检测文件编码并给出置信度
• convert_encoding - 转换文件编码
• manage_line_endings - 检测或转换换行符（CRLF/LF/混合）
• manage_bom - 检测、移除或添加 Unicode BOM
• list_encodings - 显示所有支持的编码
• get_file_info - 获取文件/目录元数据
• create_directory - 递归创建目录（mkdir -p）
• move_file - 移动或重命名文件和目录
• list_allowed_directories - 显示可访问的目录
• check_for_updates - 检查是否有更新版本可用

此外还有三个 提示词——audit_encodings、fix_mojibake、 migrate_to_utf8——由客户端作为用户命令提供。

详细参数和示例请参阅 TOOLS.md。也接受与 Claude Code 内置 Read/Write/Edit/Grep 相同形式的调用—— 别名层 会在语义完全一致时转换这些调用，因此模型的使用习惯不会导致调用失败。

不在范围内： 二进制/媒体文件读取（read_media_file）。这是一个文本 工具；Agent 使用内置工具读取图像。

支持的编码

以下编码均支持读写。可通过 encoding 参数显式指定编码名称，也可以 交由自动检测处理。

脚本 / 地区	编码
Unicode	UTF-8、UTF-16 LE/BE、UTF-32 LE/BE
西里尔字母	Windows-1251、KOI8-R、KOI8-U、CP866、CP855、ISO-8859-5、MacCyrillic
西欧	Windows-1252、ISO-8859-1、ISO-8859-15、MacRoman
中欧	Windows-1250、ISO-8859-2
希腊语	Windows-1253、ISO-8859-7
土耳其语	Windows-1254、ISO-8859-9
波罗的海和北欧	Windows-1257、ISO-8859-4、ISO-8859-10、ISO-8859-13
希伯来语、阿拉伯语、越南语、泰语	Windows-1255、1256、1258、874、ISO-8859-6、ISO-8859-8
其他拉丁字母	ISO-8859-3、ISO-8859-14、ISO-8859-16
DOS 代码页	CP437、CP850、CP852
中文	GBK、GB18030、Big5
日语和韩语	Shift_JIS、EUC-JP、ISO-2022-JP、EUC-KR

支持常见别名（cp1251、latin1、gb2312、tis-620 等）—— list_encodings 会显示包含别名的完整列表。

自动检测不会猜测 MacRoman、DOS 代码页或较少见的 ISO 编码；请显式指定。 只有通过 BOM 才能检测出 UTF-32。

配置

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

变量	描述	默认值
MCP_DEFAULT_ENCODING	未指定时，write_file 对新建文件使用的默认编码。现有文件保留检测到的编码。设置为 cp1251 可恢复 2.0.0 之前的默认值。	utf-8
MCP_DEFAULT_LINE_ENDINGS	write_file 对新建文件使用的换行符（crlf/lf）。无论如何，现有文件都会保留自己的样式。	未设置（写入时保持不变）
MCP_MEMORY_THRESHOLD	内存阈值，单位为字节。小于此值的文件会加载到内存中，以加快 I/O；较大的文件则使用流式处理。也会影响编码检测模式。	67108864（64MB）
MCP_DETECTION_CANDIDATES	以逗号分隔的列表，用于限定检测结果及其优先级顺序，例如 utf-8,windows-1252。参见限定编码范围。	未设置（不限制检测范围）
MCP_FILE_TOOLS_ALLOWED_DIRS	允许访问的目录，使用操作系统的路径列表格式（Windows 上用 ;，其他系统上用 :）。适用于只能控制 env 配置块的客户端，例如 Claude Code 插件。args 的优先级更高。	未设置
MCP_FILE_TOOLS_NO_CWD_FALLBACK	设置此项后，当 args 和 MCP_FILE_TOOLS_ALLOWED_DIRS 都未指定目录时，不再授予对工作目录的访问权限。	未设置（启用回退）

在配置中通过 env 配置块设置这些变量（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"
      }
    }
  }
}

限定编码范围

编码检测只是猜测，也有盲区：类似 MÓDULO FÍSICAMENTE ÚNICO 这样的西班牙语 CP1252 文本，可能会被误判为 GBK——每个大写重音字母后接 ASCII 字母的组合都是有效的汉字对——因此读回时会变成中文，编辑也会失败，并显示 "gbk cannot represent 2 characters"。如果你知道代码库使用什么编码，请明确指定：

"env": { "MCP_DETECTION_CANDIDATES": "utf-8,windows-1252" }

BOM 始终优先。列表内的猜测会保留其置信度；列表外的猜测会被舍弃，并由列表中最像文本的编码接替，若相同则按列表顺序决定。不符合列表中任何编码的文件会按默认编码读取，并在 read_text_file 的提示中标记为 ODD ENCODING，这样遇到异常文件时会明确提示，而不是进行猜测。未列出的编码也不会再出现在 detect_encoding 的 candidates 中。UTF-16/32 只能通过 BOM 或结构分类器识别，因此将它们列入列表也不能让它们成为通用匹配项。

旧版团队（2.0.0 之前的行为）

2.0.0 之前，新文件默认使用 cp1251；现在默认使用 utf-8。现有文件不受影响——其编码会被检测并保留——所以只有团队创建新的非 UTF-8 文件（例如包含西里尔字面量的新 Delphi 单元）时才需要注意。若要保留旧行为：

"env": { "MCP_DEFAULT_ENCODING": "cp1251" }

请将此设置提交到旧版代码库的 .mcp.json，而不是在每台机器上单独设置，这样在该代码库中工作的所有人都能获得正确的默认值，无需本地配置。

Delphi 2007 及更早版本只有在 UTF-8 文件带有 BOM 时才能读取，因此不带 BOM 的 UTF-8 文件会被默默当作 ANSI 处理。对此类代码库，请设置 cp1251（或你自己的 ANSI 代码页），让新建的西里尔字面量使用 IDE 预期的编码。无论如何，已有文件都会保留自己的编码，且没有任何工具会为它们添加 BOM。

开发

前置条件： Go 1.27+

make test    # go test -race ./...
make lint    # go vet, go fmt, staticcheck (same pinned version as CI)
make build

scripts/smoke-test 会通过 stdio 启动服务器并调用只读工具，CI 会在每次推送时运行它：

go run ./scripts/smoke-test

调试

MCP Inspector 提供了一个 Web UI，可用于调用工具并检查响应（需要 Node.js 18+）：

npx @modelcontextprotocol/inspector go run ./cmd/mcp-file-tools -- /path/to/allowed/dir

或者直接通过管道将 JSON-RPC 发送到 stdin：

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | go run ./cmd/mcp-file-tools /path/to/project

贡献

只要符合范围且能正常工作，就会被合并。 不用先问——直接发 PR 就行。 没有 CLA，没有风格审查：make test 和 make lint 通过就够了，测试 欢迎但从不强制要求。单行修复和藏在开关后面的半成品功能都算数。超出范围， 或者破坏其他人的 Agent 所依赖的工具约定，只会得到一条评论而不是被关闭。不想自己写修复？ 提一个 issue，附上文件、 它的编码，以及工具做了什么。

详情见 CONTRIBUTING.md。找到逃出允许目录的方法？那个请私下发给 SECURITY.md，不要提 issue。

分叉

分叉没问题。GPL-3.0 就是为此而设。接管项目则不行。

GPL-3.0 是许可证，不是偏好。 以任何形式分发你的分叉（公开仓库、 发布二进制、注册表列表、交付给客户的产品），你都必须：

• 保留 GPL-3.0 和 LICENSE，版权声明保持完整（§4、§5c）
• 显著说明你改了什么以及何时改的（§5a）
• 向所有收到二进制的人提供源码（§6）

警告

删除许可证或声明、以 MIT 或专有许可证重新授权，或者只发布 二进制，都属于违反许可证，而 §8 会在你这么做的那一刻终止你的权利。

**这会被执行，**顺序如下：要求合规，然后 DMCA 下架并从任何承载它的注册表或市场中移除，最后采取法律行动。合规只需一个许可证文件、一份声明和一个源码链接。 如果你不确定你发布的内容是否合规， 在 issue 里问。

是请求，不是强制： 保留署名——版权声明是法律最低要求， 一行 "Fork of mcp-file-tools" 就能告诉读者它来自哪里。给你的分叉起个自己的名字，这样在本项目名下、作者被替换的注册表列表 就不会读起来像项目搬走了，并把它的 bug 发到这里。并且先试试上游：一个 PR 胜过永远背负合并冲突， 还能把你的名字写在提交上而不是致谢列表里。

致谢

始于别人分叉、并在此重新实现的点子：

• @skyispainted - GBK/GB18030、JSON 字符串数组参数、edit_file 重试提示
• @haobiao - 独立实现的 GBK/GB18030
• Hugo Rosário - 将 MCP roots 与 CLI 允许目录合并
• @zoster81 - UTF-16 行尾与 grep、路径包含修复、写入持久性、BOM 策略、有序并发
• Mario Rial - 将检测限定到已知编码、多模式 grep

一个 PR 会把你的名字写在提交上，而不是这个列表里。

许可证

GPL-3.0 - 见 LICENSE

Copyright (C) 2026 Dimitar Grigorov。自由软件，按原样分发，不提供任何担保。