Mcp File Tools

MCP File Tools

Claude には Настройки と表示されます。「????」や Íàñòðîéêè にはなりません。

UTF-8 以外のテキストファイルを操作する MCP サーバーです。拡張子ではなくファイルのバイト列からエンコーディングを検出し、モデルには UTF-8 で渡して、元のエンコーディングで書き戻します。BOM と CRLF/LF もそのまま保持し、そのファイルを扱うレガシーツールとバイト互換性を維持します。

• 45 種類のエンコーディングに対応し、読み書き可能 — キリル文字（CP1251、KOI8-R/U、CP866/855）、Windows-125x、ISO-8859-x、DOS コードページ、MacRoman、UTF-16/UTF-32、CJK（GBK、Big5、Shift_JIS、EUC-JP/KR）に対応しています（全リスト）
• すべてのツールでエンコーディングを考慮 — edit_file、grep_text_files、search_files も読み書きと同じ方法でデコードします
• 検出結果を確認可能 — detect_encoding は文字セット、信頼度スコア、BOM の有無を報告するため、文字化けの原因を特定できます
• BOM と改行コードを正しく保持 — UTF-16 でも保持します。バイト単位で単純に書き換えるとファイルが破損する場合があります
• サンドボックス化 — すべてのパスを確認します。シンボリックリンクやジャンクションの参照先も対象です

次の用途向けに構築されています： キリル文字の UI テキストを含む Delphi/Pascal のユニット、VB6 フォーム、ローカライズされたコンテンツを含むレガシー PHP/HTML、ファイル名からエンコーディングを判断できない INI ファイルやデータファイル。

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

PR を歓迎します。すばやくマージします — CLA は不要で、スタイルレビューもありません。1 行だけの修正も歓迎です。問題を修正するためにフォークした場合は、そのままにせず修正をお戻しください。

インストール

Claude Code プラグイン（推奨）

claude plugin marketplace add dimitar-grigorov/mcp-file-tools
claude plugin install mcp-file-tools

セッション内で、/plugin marketplace add … と /plugin install … を実行します。

PATH に Node.js 18 以降が必要です。 起動スクリプトは Node スクリプトであり、Claude Code には Node が同梱されていません。Node がない場合、/mcp ではサーバーが未接続と表示されます。

初回起動時に、お使いの OS 用のバイナリを固定バージョンでダウンロードし、SHA-256 を検証してキャッシュします。開いているフォルダーに限定されるため、設定は不要です。ワークスペース外のディレクトリで使う場合や、Node のないマシンでは、手動インストールを使用してください。

手動インストールからの移行

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

ツール名も変わります。mcp__file-tools__* は mcp__plugin_mcp-file-tools_file-tools__* になるため、権限ルールを更新してください。詳しくはツールの自動承認をご覧ください。

プラグインの更新

claude plugin marketplace update mcp-file-tools
claude plugin update mcp-file-tools@mcp-file-tools

名前だけでなく、完全な plugin@marketplace ID を使用してください。または、/plugin → Marketplaces で自動更新を有効にしてください。

レジストリとディレクトリ

このサーバーは、あらゆる MCP クライアントから検索できるよう公式 MCP Registryに登録されており、Glamaにもインデックスされています。Glama ではライセンス、品質、メンテナンスの評価が A です。

手動インストール（その他の MCP クライアント、またはワークスペース外からのアクセス）

お使いのプラットフォーム用のバイナリをダウンロードし、アクセスを許可するディレクトリとともに登録します。

プラットフォーム	リリースアセット	推奨パス
Windows x64	mcp-file-tools_windows_amd64.exe	%LOCALAPPDATA%\Programs\mcp-file-tools\mcp-file-tools.exe
Linux x64	mcp-file-tools_linux_amd64	~/.local/bin/mcp-file-tools
macOS ARM64	mcp-file-tools_darwin_arm64	~/.local/bin/mcp-file-tools

Windows（CMD ではなく 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"
claude mcp add --scope user file-tools -- "$env:LOCALAPPDATA\Programs\mcp-file-tools\mcp-file-tools.exe" "C:\Projects"

Linux / macOS（表からお使いのプラットフォーム用のアセット名に置き換えてください）：

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 によるインストール（すべてのプラットフォーム）

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

その他のクライアント

Claude Desktop、VSCode、または Cursor では、設定にダウンロードしたバイナリのパスを使用します。

Claude Desktop（Windows では %APPDATA%\Claude\claude_desktop_config.json、macOS では ~/Library/Application Support/Claude/claude_desktop_config.json）：

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 には、サーバーがアクセスできるディレクトリを必要な数だけ指定します。

VSCode / Cursor（Claude Code 拡張機能）

上記のインストール手順で claude mcp add --scope user をすでに実行している場合、サーバーは VSCode ですでに利用可能になっているため、追加の設定は不要です。

VSCode だけに個別に設定するには：

claude mcp add --scope user file-tools -- "$env:LOCALAPPDATA\Programs\mcp-file-tools\mcp-file-tools.exe" "C:\Projects"

また、プロジェクトのルートに .mcp.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"]
    }
  }
}

注意： ここでは type: "stdio" が必須です。VSCode 拡張機能はワークスペースのディレクトリを自動で追加しないため、アクセスさせたいディレクトリをすべて args に指定する必要があります。後からディレクトリを追加するには、完全なリストを指定して claude mcp add を再実行してください。以前の設定に追記するのではなく、上書きされます。

OpenAI Codex CLI

Codex では MCP コマンドを直接指定するため、TOML を手動で編集する必要はありません。

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"

codex mcp list を実行して確認し、新しい Codex セッションを開始します。現在のプロジェクト外へのアクセスを許可するには、ディレクトリ引数を追加してください。

ツールの自動承認（Claude Code）

許可プロンプトを省略するには、プロジェクトのルートにある .claude/settings.local.json に追加します：

{ "permissions": { "allow": ["mcp__plugin_mcp-file-tools_file-tools__*"] } }

このプレフィックスはプラグインのインストール用です。file-tools として登録した手動インストールの場合は、代わりに mcp__file-tools__* を使用します。誤ったプレフィックスを指定したルールは何にも一致せず、エラーも表示されません。ルールが適用されるモードや、delete_file / move_file をプロンプトによる承認が必要な状態に保つ方法については、docs/extra.md を参照してください。

更新

サーバーは更新を自動で確認し、新しいバージョンが利用可能になるとツールの応答を通じて通知します。通知には、お使いのインストール方法に応じた手順が記載されています。プラグインのインストールはプラグインの更新を通じて更新されます。再ダウンロードしたバイナリは無視されます。

手動でインストールした場合は、既存のバイナリに上書きするように再ダウンロードしてください。登録をやり直す必要はありません：

1. Claude Code のセッションをすべて終了します（実行中はバイナリがロックされています）
2. 再ダウンロードします：

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"

更新チェックを無効にするには、環境変数 MCP_NO_UPDATE_CHECK=1 を設定します。

確認とアンインストール

# 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

使い方

インストール後、Claude に次のように尋ねるだけです：

• 「このディレクトリにあるすべての .pas ファイルを一覧表示して」
• 「config.ini を読み込んで、エンコーディングを判定して」
• 「サポートされているすべてのエンコーディングを表示して」
• 「CP1251 エンコーディングを使って MainForm.dfm を読み込んで」

セキュリティ： サーバーがアクセスできるのは、許可したディレクトリのみです。まず args: ["/path/to/project"] からディレクトリを取得し、次に MCP_FILE_TOOLS_ALLOWED_DIRS から取得します。どちらも指定されていない場合は、起動したディレクトリから取得します。クライアントがそのディレクトリでサーバーを起動した場合、これはワークスペースになります。引き続き MCP roots プロトコルを使用するクライアントでは、その roots も追加されます。最後のフォールバックによってドライブのルートやホームディレクトリが許可されることはありません。許可する場合は明示的に指定してください。チェックの前にパスが解決されるため、外部を指すシンボリックリンクや Windows のジャンクションはたどられず、拒否されます。

ツール

20 個のツール — テキストコンテンツを扱うツールはすべてエンコーディングに対応しています：

• read_text_file - エンコーディングを自動検出して変換しながらファイルを読み込みます
• read_multiple_files - エンコーディングに対応しながら複数のファイルを並行して読み込みます
• write_file - 指定したエンコーディングでファイルを書き込みます
• edit_file - 差分プレビューと空白の柔軟なマッチングに対応した行単位の編集です
• copy_file - ファイルを新しい場所にコピーします
• delete_file - ファイルを削除します
• list_directory - パターンによる絞り込みでディレクトリを参照します
• tree - 簡潔なインデント付きツリーを表示し、必要に応じて各ファイルのエンコーディングを注記します
• search_files - glob パターンに一致するファイルを再帰的に検索します
• grep_text_files - エンコーディングに対応した、ファイル内容の正規表現検索です
• detect_encoding - 信頼度スコア付きでファイルのエンコーディングを自動検出します
• convert_encoding - ファイルのエンコーディングを変換します
• manage_line_endings - 改行コード（CRLF/LF/混在）を検出または変換します
• manage_bom - Unicode BOM を検出、削除、または追加します
• list_encodings - サポートされているすべてのエンコーディングを表示します
• get_file_info - ファイル／ディレクトリのメタデータを取得します
• create_directory - ディレクトリを再帰的に作成します（mkdir -p）
• move_file - ファイルやディレクトリを移動または名前変更します
• list_allowed_directories - アクセス可能なディレクトリを表示します
• check_for_updates - 新しいリリースがあるか確認します

さらに、クライアントがユーザーコマンドとして表示する 3 つのプロンプト — audit_encodings、fix_mojibake、 migrate_to_utf8 があります。

詳しいパラメーターと例については、TOOLS.md をご覧ください。 Claude Code に組み込まれている Read/Write/Edit/Grep と同じ形式の呼び出しも受け付けます。 エイリアスレイヤーは、セマンティクスが完全に一致する場合にそれらを変換するため、モデルの慣習的な呼び出し方でも失敗しません。

対象外： バイナリ／メディアの読み込み（read_media_file）。これはテキストツールです。エージェントは画像の読み込みに組み込みツールを使用します。

サポートされているエンコーディング

以下はすべて読み込みと書き込みに対応しています。encoding パラメーターで明示的に指定するか、自動検出に任せてください。

スクリプト／地域	エンコーディング
Unicode	UTF-8, UTF-16 LE/BE, UTF-32 LE/BE
キリル文字	Windows-1251, KOI8-R, KOI8-U, CP866, CP855, ISO-8859-5, MacCyrillic
西ヨーロッパ	Windows-1252, ISO-8859-1, ISO-8859-15, MacRoman
中央ヨーロッパ	Windows-1250, ISO-8859-2
ギリシャ語	Windows-1253, ISO-8859-7
トルコ語	Windows-1254, ISO-8859-9
バルト諸国および北欧	Windows-1257, ISO-8859-4, ISO-8859-10, ISO-8859-13
ヘブライ語、アラビア語、ベトナム語、タイ語	Windows-1255, 1256, 1258, 874, ISO-8859-6, ISO-8859-8
その他のラテン文字	ISO-8859-3, ISO-8859-14, ISO-8859-16
DOS コードページ	CP437, CP850, CP852
中国語	GBK, GB18030, Big5
日本語および韓国語	Shift_JIS, EUC-JP, ISO-2022-JP, EUC-KR

一般的な別名（cp1251、latin1、gb2312、tis-620 など）も使用できます — list_encodings では、別名を含む一覧全体を確認できます。

自動検出では MacRoman、DOS コードページ、および使用頻度の低い ISO テーブルは推測されません。これらは明示的に指定してください。UTF-32 は BOM がある場合のみ検出されます。

設定

サーバーは環境変数で設定できます。

変数	説明	デフォルト
MCP_DEFAULT_ENCODING	write_file で新規ファイルにエンコーディングが指定されていない場合に使用するデフォルトのエンコーディングです。既存ファイルは検出されたエンコーディングを維持します。2.0.0 より前のデフォルトに戻すには、cp1251 を設定します。	utf-8
MCP_DEFAULT_LINE_ENDINGS	write_file で新規ファイルに使用する改行コード（crlf／lf）です。既存ファイルは、いずれの場合もそれぞれのスタイルを維持します。	未設定（変更せずに書き込み）
MCP_MEMORY_THRESHOLD	メモリしきい値（バイト単位）です。このサイズより小さいファイルは I/O を高速化するためにメモリに読み込まれ、大きいファイルにはストリーミングが使用されます。エンコーディングの検出モードにも影響します。	67108864（64MB）
MCP_DETECTION_CANDIDATES	検出結果として許可する候補を優先順位順に指定する、カンマ区切りのリストです。例：utf-8,windows-1252。エンコーディング候補の固定を参照してください。	未設定（検出を制限しない）
MCP_FILE_TOOLS_ALLOWED_DIRS	OS のパスリスト（Windows では ;、それ以外では :）で指定する、許可されたディレクトリです。Claude Code プラグインのように、制御できるブロックが env のみのクライアント向けです。args によって上書きされます。	未設定
MCP_FILE_TOOLS_NO_CWD_FALLBACK	args と MCP_FILE_TOOLS_ALLOWED_DIRS のどちらにもディレクトリが指定されていない場合に、作業ディレクトリの許可を無効にするには設定します。	未設定（フォールバック有効）

設定ファイルの env ブロックで設定します（Claude Desktop の例）。

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

エンコーディング候補の固定

検出は推測であり、推測には盲点があります。スペイン語の CP1252 である MÓDULO FÍSICAMENTE ÚNICO は、もっともらしい GBK として判定されることがあります。ASCII 文字の前にある大文字のアクセント付き文字は、どれも有効な漢字のペアだからです。そのため、中国語として読み込まれ、編集時に "gbk cannot represent 2 characters" というエラーが発生します。リポジトリに含まれるエンコーディングがわかっている場合は、指定してください。

"env": { "MCP_DETECTION_CANDIDATES": "utf-8,windows-1252" }

BOM がある場合は、常に BOM が優先されます。推測されたエンコーディングがリスト内にあれば、その信頼度が維持されます。リスト外にある場合は除外され、リスト内でテキストとしてもっとも適切に読み込めるエンコーディングが代わりに選ばれます。同順位の場合はリストの順序で決まります。どの候補にも当てはまらないファイルはデフォルトで読み込まれ、read_text_file のヒントに ODD ENCODING として報告されます。そのため、見慣れないファイルは推測されるのではなく、明示的に通知されます。リストにないエンコーディングは、detect_encoding の candidates にも表示されなくなります。UTF-16／32 は BOM または構造分類によってのみ特定されるため、リストに追加しても汎用的な候補にはなりません。

以前の動作を使うチーム（2.0.0 より前の動作）

2.0.0 より前は、新規ファイルのデフォルトが cp1251 でしたが、現在は utf-8 です。既存ファイルには影響がありません。エンコーディングは検出されて維持されるため、影響するのは、キリル文字リテラルを含む新しい Delphi ユニットなど、チームで UTF-8 以外の新規ファイルを作成する 場合のみです。以前の動作を維持するには、次のようにします。

"env": { "MCP_DEFAULT_ENCODING": "cp1251" }

マシンごとに設定するのではなく、レガシーリポジトリの .mcp.json にコミットしてください。そうすれば、そのリポジトリで作業する全員がローカルで設定しなくても適切なデフォルトを使用できます。

Delphi 2007 以前では、BOM が付いた UTF-8 のみを読み取るため、BOM のない UTF-8 ファイルは警告なしに ANSI として扱われます。そのようなリポジトリでは cp1251（または独自の ANSI コードページ）を設定すると、新しいキリル文字リテラルが IDE の想定するエンコーディングで書き込まれます。既存ファイルはどちらの場合もそれぞれのエンコーディングを維持し、ツールが既存ファイルに BOM を追加することはありません。

開発

前提条件： Go 1.27+

make test    # go test -race ./...
make lint    # go vet, go fmt, staticcheck (same pinned version as CI)
make build

scripts/smoke-test は stdio 経由でサーバーを起動し、読み取り専用ツールを呼び出します。これはプッシュのたびに CI で実行されます。

go run ./scripts/smoke-test

デバッグ

MCP Inspector を使うと、ツールの呼び出しやレスポンスの確認ができる Web UI を利用できます（Node.js 18+ が必要です）。

npx @modelcontextprotocol/inspector go run ./cmd/mcp-file-tools -- /path/to/allowed/dir

または、JSON-RPC を標準入力に直接パイプします。

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | go run ./cmd/mcp-file-tools /path/to/project

貢献

スコープに合っていて動作するものは、マージされます。 先に尋ねず、そのまま PR を送ってください。 CLA もスタイルレビューも不要です。make test と make lint が通れば十分です。テストも歓迎しますが、必須ではありません。一行の修正も、フラグで有効化される未完成の機能も対象です。スコープ外のものや、他のエージェントが依存しているツールの契約を破るものについては、クローズするのではなくコメントします。自分で修正を書くつもりはありませんか？ ファイル名、エンコーディング、ツールが行ったことを添えて、 issue を作成してください。

詳細は CONTRIBUTING.md をご覧ください。許可されたディレクトリから抜け出せる方法を見つけた場合は、issue ではなく、非公開で SECURITY.md に報告してください。

フォーク

フォークしても問題ありません。そのための GPL-3.0 です。ただし、プロジェクトを乗っ取ることは認められません。

GPL-3.0 はライセンスであり、単なる希望ではありません。 フォークをどのような形でも配布する場合（公開リポジトリ、リリースバイナリ、レジストリへの掲載、顧客に提供する製品など）、次の義務があります。

• GPL-3.0 と LICENSE を維持し、著作権表示をそのまま残すこと（§4、§5c）
• 変更内容とその時期を目立つ形で明記すること（§5a）
• バイナリを提供したすべての人にソースコードを提供すること（§6）

警告

ライセンスや表示を削除すること、MIT またはプロプライエタリライセンスに再ライセンスすること、バイナリのみを配布することはライセンス違反です。違反した時点で §8 により権利が終了します。

以下の順序で執行します。 まず遵守を求め、それに続いて DMCA に基づく削除要請と、掲載されているレジストリまたはマーケットプレイスからの削除を行い、その後、法的措置を取ります。遵守に必要なのは、ライセンスファイル、表示、ソースコードへのリンクをそれぞれ一つずつ用意することだけです。 配布するものが要件を満たしているか不明な場合は、 issue でお尋ねください。

お願いであり、強制ではありません。 クレジットは残してください。著作権表示は法的な最低限ですが、"Fork of mcp-file-tools" という一行があれば、読者に出自を伝えられます。また、フォークには独自の名前を付けてください。作者名だけを差し替えてこの名前でレジストリに掲載すると、プロジェクトが移転したかのように見え、バグ報告がこちらに届いてしまいます。そして、まずは上流への貢献を検討してください。PR を送れば、マージの競合を延々と抱えずに済み、クレジット一覧ではなくコミットに名前が残ります。

クレジット

他の方のフォークで生まれ、こちらで再実装したアイデア：

• @skyispainted - GBK/GB18030、JSON 文字列の配列引数、edit_file の再試行ヒント
• @haobiao - GBK/GB18030（独自に実装）
• Hugo Rosário - MCP roots と CLI の許可ディレクトリの統合
• @zoster81 - UTF-16 の改行と grep、パス包含チェックの修正、書き込みの耐久性、BOM ポリシー、順序付き並行処理
• Mario Rial - 既知のエンコーディングへの検出の限定、複数パターンの grep

PR を送れば、この一覧ではなくコミットに名前が残ります。

ライセンス

GPL-3.0 - 詳細は LICENSE をご覧ください。

Copyright (C) 2026 Dimitar Grigorov. フリーソフトウェアです。いかなる保証もありません。