MCP File Tools

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.

• 45 encodings, read and write — Cyrillic (CP1251, KOI8-R/U, CP866/855), Windows-125x, ISO-8859-x, DOS code pages, MacRoman, UTF-16/UTF-32, CJK (GBK, Big5, Shift_JIS, EUC-JP/KR) (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](https://nodejs.org) 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 -- "$env: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"

To disable update checks, set the environment variable MCP_NO_UPDATE_CHECK=1.

Verify & Uninstall

# 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

How to Use

Once installed, just ask Claude:

• "List all .pas files in this directory"
• "Read config.ini and detect its encoding"
• "Show all supported encodings"
• "Read MainForm.dfm using CP1251 encoding"

Security: the server reaches only the directories you allowed. It takes them from args: ["/path/to/project"] first, then MCP_FILE_TOOLS_ALLOWED_DIRS, and failing both from the directory it was started in — the workspace, when a client launches it there. Clients that still speak the MCP roots protocol add their roots on top. A drive root or your home directory is never granted by that last fallback; name it explicitly instead. Paths are resolved before the check, so a symlink or Windows junction pointing outside is rejected rather than followed.

Tools

20 tools — every one that touches text content is encoding-aware:

• read_text_file - Read files with encoding auto-detection and conversion
• read_multiple_files - Read multiple files concurrently with encoding support
• write_file - Write files in specific encodings
• edit_file - Line-based edits with diff preview and whitespace-flexible matching
• copy_file - Copy a file to a new location
• delete_file - Delete a file
• list_directory - Browse directories with pattern filtering
• tree - Compact indented tree view, optionally annotated with each file's encoding
• [search_files](docs/TOOLS.