MCP File Tools

🚀 MCP File Tools

MCP File Tools is an MCP server designed for file operations, offering support for non-UTF-8 encodings. It can auto-detect and convert 22 different encodings, including Cyrillic, Windows-125x, ISO-8859, KOI8, and UTF-16. This ensures that AI assistants can read and write legacy files without data corruption. It's ideal for Delphi/Pascal projects, legacy VB6 apps, old PHP/HTML sites, and config files containing non-UTF-8 text.

🚀 Quick Start

Once installed, simply ask Claude commands like:

• "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 Note: The server only accesses directories you explicitly allow. Claude Desktop/Code automatically provide workspace directories, or you can manually specify directories in the config args: ["/path/to/project"].

✨ Features

• Encoding Support: Auto-detects and converts 22 encodings, including Unicode, Cyrillic, Western European, Central European, Greek, Turkish, and others.
• Multiple File Operations: Offers 19 tools for various file operations, such as reading, writing, editing, copying, deleting, and more.
• Security: All operations are restricted to allowed directories only.

📦 Installation

MCP Registry

This server is listed in the Official MCP Registry for easy 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

Claude Desktop

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

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

The args array specifies allowed directories the server can access. You can add as many directories as needed.

VSCode / Cursor (Claude Code extension)

If you've already run claude mcp add --scope user during installation, the server is available in VSCode without extra config. To configure separately for VSCode:

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 doesn't automatically add the workspace directory, so 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).

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__list_encodings",
      "mcp__file-tools__get_file_info",
      "mcp__file-tools__create_directory",
      "mcp__file-tools__list_allowed_directories"
    ]
  }
}

This auto-approves safe read-only and editing file-tools operations, along with common shell commands and web search. Destructive operations (delete_file, move_file) and WebFetch are intentionally excluded. Claude will ask before using them. Adjust as needed.

Verify & Uninstall

# Check if the server is configured
claude mcp list

# Remove the server
claude mcp remove file-tools

💻 Usage Examples

Basic Usage

Once installed, you can interact with the server through Claude. For example:

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

Advanced Usage

You can also use the server's commands directly via JSON-RPC. For example, to list all tools:

{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}

📚 Documentation

The server provides 19 tools for file operations with automatic encoding conversion:

• - Read files with encoding auto-detection and conversion
• - Read multiple files concurrently with encoding support
• - Write files in specific encodings
• - Line-based edits with diff preview and whitespace-flexible matching
• - Copy a file to a new location
• - Delete a file
• - Browse directories with pattern filtering
• - Compact indented tree view (85% fewer tokens than JSON)
• - Get recursive tree view as JSON (deprecated, use tree)
• - Recursively search for files matching glob patterns
• - Regex search in file contents with encoding support
• - Auto-detect file encoding with confidence score
• - Convert file between encodings
• - Detect line ending style (CRLF/LF/mixed)
• - Show all supported encodings
• - Get file/directory metadata
• - Create directories recursively (mkdir -p)
• - Move or rename files and 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.

🔧 Technical Details

The server can be configured via environment variables:

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

📄 License

This project is licensed under the GPL-3.0 license. See LICENSE for details.