MCP File Tools

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

MCP server for file operations with non-UTF-8 encoding support. Auto-detects and converts 22 encodings (Cyrillic, Windows-125x, ISO-8859, KOI8, UTF-16) so AI assistants can read and write legacy files without corrupting data.

Perfect for: Delphi/Pascal projects, legacy VB6 apps, old PHP/HTML sites, config files with non-UTF-8 text.

What It Does

Provides 21 tools for file operations with automatic encoding conversion:

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 (85% fewer tokens than JSON)
directory_tree - Get recursive tree view as JSON (deprecated, use tree)
search_files - Recursively search for files matching glob patterns
grep_text_files - Regex search in file contents with encoding support
detect_encoding - Auto-detect file encoding with confidence score
convert_encoding - Convert file between encodings
detect_line_endings - Detect line ending style (CRLF/LF/mixed)
change_line_endings - Convert line endings to LF or CRLF
manage_bom - Detect, strip, or add Unicode BOM
list_encodings - Show all supported encodings
get_file_info - Get file/directory metadata
create_directory - Create directories recursively (mkdir -p)
move_file - Move or rename files and directories
list_allowed_directories - Show accessible directories

Supported encodings (22 total):

Unicode: UTF-8, UTF-16 LE, UTF-16 BE (with BOM detection for UTF-16 and UTF-32)
Cyrillic: Windows-1251, KOI8-R, KOI8-U, CP866, ISO-8859-5
Western European: Windows-1252, ISO-8859-1, ISO-8859-15
Central European: Windows-1250, ISO-8859-2
Greek: Windows-1253, ISO-8859-7
Turkish: Windows-1254, ISO-8859-9
Other: Hebrew (1255), Arabic (1256), Baltic (1257), Vietnamese (1258), Thai (874)

See TOOLS.md for detailed parameters and examples.

Security: All operations restricted to allowed directories only.

Installation

MCP Registry

This server is listed in the Official MCP Registry for discovery.

Windows x64

Note: Run these commands in PowerShell, not in 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

Go Install (All Platforms)

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

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

The args array specifies allowed directories the server can access. Add as many directories 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" "D:\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: The type: "stdio" field is required. The args array specifies allowed directories — the VSCode extension does not automatically add the workspace directory, so you must list all directories you want to access. To add more directories later, re-run the claude mcp add command with all directories listed (it overwrites the previous config).

OpenAI Codex CLI

Codex does not have an mcp add command -- you need to edit ~/.codex/config.toml manually.

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"

Then add to ~/.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"]

Auto-approve All Tools (Claude Code)

To skip permission prompts for all file-tools commands, create .claude/settings.local.json in your project root:

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

This auto-approves safe read-only and editing file-tools operations plus common shell commands and web search. Destructive operations (delete_file, move_file) and WebFetch are intentionally excluded — Claude will ask before using them. Adjust to your needs.

Update

The server checks for updates automatically and notifies you through tool responses when a newer version is available. To update:

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

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 if the server is configured
claude mcp list

# Remove the server
claude mcp remove 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 only accesses directories you explicitly allow:

Automatic: Claude Desktop/Code provide workspace directories automatically
Manual: Specify directories in config args: ["/path/to/project"]

Configuration

The server can be configured via environment variables:

Variable	Description	Default
`MCP_DEFAULT_ENCODING`	Default encoding for `write_file` when none specified	`cp1251`
`MCP_MEMORY_THRESHOLD`	Memory threshold in bytes. Files smaller are loaded into memory for faster I/O; larger files use streaming. Also affects encoding detection mode.	`67108864` (64MB)

To override, set environment variables in your config (Claude Desktop example):

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

Use Cases

Legacy Codebases

Many legacy projects use non-UTF-8 encodings that AI assistants can't handle natively:

Delphi/Pascal (Windows-1251): Source files with Cyrillic UI text
Visual Basic 6 (Windows-1252): Forms and config files with Western European characters
Legacy PHP/HTML (CP1251, ISO-8859-1): Web apps with localized content
Old config files (Various): INI, properties, registry files with legacy encodings

How it works:

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

The original encoding is preserved - files remain compatible with legacy tools.

Development

Prerequisites: Go 1.23+

# Run tests
go test ./...

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

Debugging with MCP Inspector

MCP Inspector provides a web UI for testing MCP servers.

Prerequisites: 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

Opens a browser where you can view tools, call them with custom arguments, and inspect responses.

Manual Debugging

Run the server with an allowed directory and send JSON-RPC commands via stdin:

# Specify allowed directory
go run ./cmd/mcp-file-tools /path/to/project

Example commands (paste into terminal):

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

License

GPL-3.0 - see LICENSE

Name		Name	Last commit message	Last commit date
Latest commit History 133 Commits
.github		.github
cmd/mcp-file-tools		cmd/mcp-file-tools
filetoolsserver		filetoolsserver
internal		internal
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.goreleaser.yml		.goreleaser.yml
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
TOOLS.md		TOOLS.md
go.mod		go.mod
go.sum		go.sum
server.json		server.json
smithery.yaml		smithery.yaml
test_server.go		test_server.go

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

MCP File Tools

What It Does

Installation

MCP Registry

Windows x64

Linux x64

macOS ARM64

Go Install (All Platforms)

Other Clients

Auto-approve All Tools (Claude Code)

Update

Verify & Uninstall

How to Use

Configuration

Use Cases

Legacy Codebases

Development

Debugging with MCP Inspector

Manual Debugging

License

About

Uh oh!

Releases 17

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

MCP File Tools

What It Does

Installation

MCP Registry

Windows x64

Linux x64

macOS ARM64

Go Install (All Platforms)

Other Clients

Auto-approve All Tools (Claude Code)

Update

Verify & Uninstall

How to Use

Configuration

Use Cases

Legacy Codebases

Development

Debugging with MCP Inspector

Manual Debugging

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 17

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages