MCP FileEncoding

MCP server that solves the issue of garbled text when AI coding assistants read/write non-UTF-8 files (such as GBK/GB18030) on Windows.

It automatically detects the encoding during read operations and converts it to UTF-8 for the AI, and automatically converts it back to the original encoding during write operations, making it completely transparent to the AI.

Background

In Windows Chinese environments, many projects (C/C++, Lisp, etc.) save source files using GBK encoding. AI coding assistants default to reading these files with UTF-8, causing Chinese comments and strings to become garbled. This MCP handles encoding conversion automatically during file I/O, allowing the AI to correctly process non-UTF-8 files.

Related MCP server: filesystem-mcp

Supported Encodings

• UTF-8 / UTF-8 BOM

• GBK / GB2312

• GB18030

• Other encodings supported by Python codecs

Installation

git clone https://github.com/jidzhang/mcp-fileencoding.git
cd mcp-fileencoding
pip install -r requirements.txt

Configuration

Claude Code

claude mcp add fileencoding -- python /path/to/mcp-fileencoding/src/server.py

Claude Desktop / Cursor / Other MCP Clients

Add to your MCP configuration file (the file path varies by client; refer to the corresponding client documentation):

{
  "mcpServers": {
    "fileencoding": {
      "command": "python",
      "args": ["/path/to/mcp-fileencoding/src/server.py"]
    }
  }
}

Usage

Once configured, the AI will automatically gain access to the following 5 tools.

Tool List

Method 1: PreToolUse Hook (Recommended)

Using the Claude Code Hook mechanism, the AI automatically checks the file type and prompts the use of MCP whenever it calls Read/Write/Edit tools. This is more reliable than system prompts and will not fail during multi-turn conversations.

Create .claude/settings.json in the project root directory:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Write|Edit",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "检查 $ARGUMENTS 中的文件路径，如果文件扩展名是 .cpp、.h 或 .lsp，则：\n- 对于 Read 操作：使用 mcp__fileencoding__read_file_with_encoding 代替 Read 工具\n- 对于 Write/Edit 操作：使用 mcp__fileencoding__write_file_with_encoding 代替 Write/Edit 工具\n\n返回 JSON: {\"hookSpecificOutput\": {\"hookEventName\": \"PreToolUse\", \"additionalContext\": \"提示信息\"}}"
          }
        ]
      }
    ]
  }
}

Modify the matched file extensions (.cpp, .h, .lsp, etc.) as needed.

Method 2: System Prompt

Add the prompt in Claude Code via the --system-prompt parameter or the project's CLAUDE.md file:

claude --system-prompt "在读取和修改 .cpp/.h/.lsp/.txt 等文本文件时，使用 fileencoding MCP。.py/.js/.html 等文件不需要使用。其他文件一般不需要使用，只有遇到读取文本乱码后才尝试使用。"

Note: System prompts may be ignored by the AI in long conversations; the PreToolUse Hook is a more reliable choice.

Workflow

Taking editing a GBK-encoded .cpp file as an example:

1. AI calls read_file_with_encoding to read the file → automatically detects it as GBK → returns UTF-8 content to the AI

2. After the AI understands the content, it calls edit_file_with_encoding to modify it → automatically writes it back to the file using GBK

3. The file encoding remains unchanged, ensuring compatibility with other tools

Notes

• Encoding records are stored in memory and cleared when the MCP server restarts

• If the encoding record is lost when writing a file, you need to manually specify the encoding parameter

• Detection is based on file content; short text may not be accurate enough. It is recommended that the file content contains at least several dozen Chinese characters

Development

Install Development Dependencies

pip install -r requirements.txt
pip install pytest pyright

Run Tests

python -m pytest tests/ -v

Type Checking

npx pyright src/

The project uses pyright strict mode; all source code type checks must pass with zero errors.

Project Structure

src/
├── server.py          # MCP 服务器入口，工具定义和请求处理
├── detector.py        # 编码检测（charset-normalizer + GBK 回退）
├── converter.py       # 编码转换（字节 ↔ UTF-8）
└── encoding_store.py  # 内存编码记录存储
tests/
├── test_server.py     # 服务器 handler 测试
├── test_detector.py   # 编码检测测试
├── test_converter.py  # 编码转换测试
└── test_encoding_store.py  # 存储模块测试

Dependencies

• Python >= 3.10

• mcp >= 1.0.0

• charset-normalizer >= 3.0.0

License

MIT