MCP File Tools

Claude sees Настройки — not ???? or Íàñòðîéêè.

MCP server for file operations on text that isn't UTF-8. It detects the encoding from the file's bytes rather than its extension, hands the model UTF-8, and writes back in the original encoding — BOM and CRLF/LF intact, still byte-compatible with whatever legacy tool owns the file.

• 25 encodings, read and write — Cyrillic (CP1251, KOI8-R/U, CP866), Windows-125x, ISO-8859-x, UTF-16 LE/BE, GBK/GB18030 (full list)
• Encoding-aware across the whole tool set — edit_file, grep_text_files and search_files decode the same way, not just read and write
• Detection you can inspect — detect_encoding reports the charset, a confidence score and any BOM, so garbled text becomes diagnosable
• BOM and line endings are first-class — including on UTF-16, where a naive byte-level rewrite corrupts the file
• Sandboxed — every path, symlink and junction targets included, is checked against the directories you allowed

Built for: Delphi/Pascal units with Cyrillic UI text, VB6 forms, legacy PHP/HTML with localized content, and INI or data files whose encoding you can't tell from the filename.

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

PRs welcome and merged fast — no CLA, no style review, one-line fixes count. Forked this to fix something? Please send it back instead.

Installation

Claude Code plugin (recommended)

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

Inside a session: /plugin marketplace add … and /plugin install ….

Requires Node.js 18+ on your PATH. The launcher is a Node script and Claude Code does not bundle Node; without it /mcp shows the server as not connected.

First launch downloads the binary for your OS at a pinned version, verifies its SHA-256 and caches it. It is scoped to the folder you have open, so there is nothing to configure. For directories outside the workspace, or a machine without Node, use a manual install.

Coming from a manual install

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

Tool names change too: mcp__file-tools__* becomes mcp__plugin_mcp-file-tools_file-tools__*, so update your permission rules, see Auto-approve tools.

Updating the plugin

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

Use the full plugin@marketplace id, not the bare name, or turn on auto-update in /plugin → Marketplaces.

Registries and directories

This server is listed in the Official MCP Registry for discovery by any MCP client, and indexed on Glama, which scores it A for license, quality and maintenance.

Manual install (other MCP clients, or access outside your workspace)

Download the binary for your platform, then register it with the directories it may access.

Windows (PowerShell, not 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 (swap the asset name from the table for your platform):

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 install (all platforms)

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

Other Clients

For Claude Desktop, VSCode, or Cursor, use the downloaded binary path in your config:

Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

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 lists the directories the server may access — as many as you need.

VSCode / Cursor (Claude Code extension)

If you already ran claude mcp add --scope user from the installation steps above, the server is already available in VSCode — no extra config needed.

To configure separately for VSCode only:

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

Alternatively, create a per-project config by adding .mcp.json to your project root:

{
  "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"]
    }
  }
}

Note: type: "stdio" is required here. The VSCode extension does not add the workspace directory by itself, so args must list every directory you want reachable. Adding one later means re-running claude mcp add with the full list — it overwrites the previous config rather than appending.

OpenAI Codex CLI

Codex takes a direct MCP command, so no manual TOML editing is needed.

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"

Run codex mcp list to verify it, then start a new Codex session. Add more directory arguments to grant access outside the current project.

Auto-approve tools (Claude Code)

To skip the permission prompts, add to .claude/settings.local.json in your project root:

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

That prefix is the plugin install; a manual one registered as file-tools is mcp__file-tools__* instead, and a rule with the wrong prefix matches nothing and fails quietly. Which modes the rules affect, and keeping delete_file / move_file behind a prompt, are in docs/extra.md.

Update

The server checks for updates automatically and notifies you through tool responses when a newer version is available; the notice carries the steps for your install. Plugin installs update through Updating the plugin — a re-downloaded binary is ignored there.

For a manual install, re-download the binary over the existing one — the registration does not need repeating:

1. Close all Claude Code sessions (the binary is locked while running)
2. Re-download:

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"