# MCP File Tools
Non-UTF-8 file encoding server: Cyrillic (CP1251, KOI8), Windows-1250-1258, ISO-8859 with auto-detection and Unicode conversion. Lets AI assistants read and write files in legacy encodings that would otherwise corrupt data.
**Perfect for:** Delphi/Pascal projects, legacy VB6 apps, old PHP/HTML sites, config files with non-UTF-8 text.
## What It Does
Provides 19 tools for file operations with automatic encoding conversion:
- [`read_text_file`](TOOLS.md#read_text_file) - Read files with encoding auto-detection and conversion
- [`read_multiple_files`](TOOLS.md#read_multiple_files) - Read multiple files concurrently with encoding support
- [`write_file`](TOOLS.md#write_file) - Write files in specific encodings
- [`edit_file`](TOOLS.md#edit_file) - Line-based edits with diff preview and whitespace-flexible matching
- [`copy_file`](TOOLS.md#copy_file) - Copy a file to a new location
- [`delete_file`](TOOLS.md#delete_file) - Delete a file
- [`list_directory`](TOOLS.md#list_directory) - Browse directories with pattern filtering
- [`tree`](TOOLS.md#tree) - Compact indented tree view (85% fewer tokens than JSON)
- [`directory_tree`](TOOLS.md#directory_tree-deprecated) - Get recursive tree view as JSON (deprecated, use `tree`)
- [`search_files`](TOOLS.md#search_files) - Recursively search for files matching glob patterns
- [`grep_text_files`](TOOLS.md#grep_text_files) - Regex search in file contents with encoding support
- [`detect_encoding`](TOOLS.md#detect_encoding) - Auto-detect file encoding with confidence score
- [`convert_encoding`](TOOLS.md#convert_encoding) - Convert file between encodings
- [`detect_line_endings`](TOOLS.md#detect_line_endings) - Detect line ending style (CRLF/LF/mixed)
- [`list_encodings`](TOOLS.md#list_encodings) - Show all supported encodings
- [`get_file_info`](TOOLS.md#get_file_info) - Get file/directory metadata
- [`create_directory`](TOOLS.md#create_directory) - Create directories recursively (mkdir -p)
- [`move_file`](TOOLS.md#move_file) - Move or rename files and directories
- [`list_allowed_directories`](TOOLS.md#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](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](https://registry.modelcontextprotocol.io/?search=mcp-file-tools) for discovery.
### Windows x64
```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"
# Install with Claude Code
claude mcp add file-tools "$env:LOCALAPPDATA\Programs\mcp-file-tools\mcp-file-tools.exe"
```
### Linux x64
```bash
# 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
claude mcp add file-tools ~/.local/bin/mcp-file-tools
```
### macOS ARM64
```bash
# 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
claude mcp add file-tools ~/.local/bin/mcp-file-tools
```
### Go Install (All Platforms)
```bash
# 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 (Linux/macOS)
claude mcp add file-tools $(go env GOPATH)/bin/mcp-file-tools
```
```powershell
# Add to Claude Code (Windows PowerShell)
claude mcp add file-tools "$(go env GOPATH)\bin\mcp-file-tools.exe"
```
### 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):
```json
{
"mcpServers": {
"file-tools": {
"command": "/path/to/mcp-file-tools"
}
}
}
```
**VSCode / Cursor** - Two options:
**Option 1: Global config (recommended)** - Available in all projects
CLI command (easiest):
```powershell
claude mcp add --scope user file-tools -- "%LOCALAPPDATA%\Programs\mcp-file-tools\mcp-file-tools.exe" "D:\Projects"
```
Or manually edit `%USERPROFILE%\.claude.json`:
```json
{
"mcpServers": {
"file-tools": {
"type": "stdio",
"command": "C:\\Users\\YOUR_NAME\\AppData\\Local\\Programs\\mcp-file-tools\\mcp-file-tools.exe",
"args": ["D:\\Projects"]
}
}
}
```
**Option 2: Per-project config** - Create `.mcp.json` in project root:
```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"]
}
}
}
```
**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.
## 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) |
**Example (Claude Desktop config):**
```json
{
"mcpServers": {
"file-tools": {
"command": "/path/to/mcp-file-tools",
"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+
```bash
# Run tests
go test ./...
# Build
go build -o mcp-file-tools ./cmd/mcp-file-tools
```
### Debugging with MCP Inspector
[MCP Inspector](https://github.com/modelcontextprotocol/inspector) provides a web UI for testing MCP servers.
**Prerequisites:** Node.js v18+
```bash
# 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:
```bash
# Specify allowed directory
go run ./cmd/mcp-file-tools /path/to/project
```
Example commands (paste into terminal):
```json
{"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](LICENSE)
