Claude File Manager MCP

An MCP server for Claude that can create, read, edit, copy, move and delete files and folders — plus images, bulk replacements, ZIP archives, a compact project tree, and an optional terminal with background processes.

It runs locally over stdio, without internet access or third-party services.

Features

That is 27 tools with the terminal enabled and 22 without. The five terminal tools are disabled unless MCP_ALLOW_SHELL=1 is set. All other tools work with files only.

Related MCP server: FS-MCP

Windows installation (prebuilt installer)

Download ClaudeFileManager-Setup-1.3.0.exe.

1. Run the installer. If Windows shows the blue SmartScreen window, click More info → Run anyway (the file has no digital signature).

2. It installs without administrator rights into %LOCALAPPDATA%\ClaudeFileManager. Node.js is bundled — nothing else needs to be installed.

3. On the last screen the installer shows the instructions and offers "Run setup now".

4. In the browser choose a folder → Use this folder → Connect to Claude Desktop → restart Claude Desktop.

"Claude File Manager" shortcuts appear in the Start menu and (optionally) on the desktop. Uninstall via Settings → Apps.

Portable version: ClaudeFileManager-Portable-1.3.0.zip — extract anywhere and run start-ui.cmd. No installation required.

Building the installer

winget install --id JRSoftware.InnoSetup -e
npm run build:installer

The output appears in installer\out. The script copies the Node runtime, installs production dependencies, draws the icon and builds both the .exe and the portable .zip.

Run from source

git clone https://github.com/sadd11/claude-file-manager-mcp.git
cd claude-file-manager-mcp
npm install

Setup through the UI (recommended)

npm run ui

Or double-click start-ui.cmd.

The page http://127.0.0.1:4317 opens:

1. Choose a folder — browse drives and subfolders, paste a path manually, or click Browse… and pick a folder in the system dialog.

2. Click Use this folder.

3. Optionally add more folders under Additional folders — Claude can then work in all of them, and can choose the right one itself.

4. Click Connect to Claude Desktop.

5. Fully close and reopen Claude Desktop.

The UI also provides:

• Check server — actually starts the MCP server and lists the working tools;

• a "Connected to Claude Desktop" indicator that shows which folders are used;

• a list of recent folders;

• a History and recovery section with Trash, Backups, Commands and Activity tabs — deleted items and file versions can be restored with one click, without writing a prompt;

• an Open button that reveals the selected folder in Explorer;

• an "Allow terminal commands" switch (see below);

• the JSON config and a ready-made Claude Code command.

The UI creates (or carefully updates) %APPDATA%\Claude\claude_desktop_config.json, saves a backup, and shows the JSON config and Claude Code command if you prefer to connect manually.

Keep the console window open while you use the UI. Stop it with Ctrl+C.

Manual setup

Check that the server starts:

npm start

The server starts and waits for JSON-RPC on stdin — this is expected; nothing must be written to stdout. Stop it with Ctrl+C.

Connecting to Claude Desktop manually

1. Open the config file: %APPDATA%\Claude\claude_desktop_config.json (create it if it does not exist).

2. Add the server:

{
  "mcpServers": {
    "files": {
      "command": "node",
      "args": ["C:\\path\\to\\claude-file-manager-mcp\\src\\index.js"],
      "env": {
        "MCP_FILE_ROOT": "C:\\path\\to\\your\\project"
      }
    }
  }
}

3. Fully close and reopen Claude Desktop.

4. A tools icon appears in the chat — the files server is ready.

MCP_FILE_ROOT is the folder the server is allowed to work in. Point it at your project so Claude cannot accidentally change something elsewhere. To allow several folders, use MCP_FILE_ROOTS instead with paths separated by ; (Windows) or : (macOS/Linux). Relative paths resolve against the first folder. Add "MCP_ALLOW_SHELL": "1" to env to enable the optional terminal tools.

Connecting to Claude Code (CLI)

claude mcp add files --scope user `
  --env MCP_FILE_ROOT="C:\path\to\your\project" `
  -- node "C:\path\to\claude-file-manager-mcp\src\index.js"

Verify:

claude mcp list

Trash, backups and undo

The server creates a service directory .mcp inside the working folder:

.mcp/
├─ trash/       deleted files and folders
├─ backups/     copies saved before edits
├─ trash.json   trash index
├─ activity.json change history
└─ commands.log terminal command log (if the terminal is enabled)

The service folder lives in the first allowed folder. With several roots, trash, backups and history are still stored there.

• delete_path by default does not destroy the file; it moves it to the trash. Restore it with restore_path or undo_last_change.

• edit_file, multi_edit, write_file and append_file save a copy of the old version before modifying.

• replace_in_files backs up every changed file and records a single undo step, so one undo_last_change reverts the whole bulk replacement.

• zip_path and unzip_path can be undone when they create a new path.

• undo_last_change reverts the last action; several steps can be undone.

• Permanent deletion happens only with permanent=true.

• The setup UI shows the same trash, backups, commands and activity, with Restore buttons. A backup restore first saves the current version as a new backup, so it can be undone too.

If your project is under git, add .mcp/ to its .gitignore.

Terminal tool (optional)

run_command lets Claude run a shell command in the chosen folder — for example npm test, git status or a build script. It is off by default so that a plain installation stays file-only.

Enable it in one of these ways:

• tick Allow terminal commands (run_command) in the setup UI and click Connect to Claude Desktop again;

• add "MCP_ALLOW_SHELL": "1" to the env block of the files server in the Claude Desktop config;

• pass --env MCP_ALLOW_SHELL=1 to claude mcp add.

What it does:

• runs in the same allowed folder as the file tools (outside folders are rejected unless MCP_ALLOW_OUTSIDE_ROOT=1);

• returns stdout, stderr and the exit code;

• stops the command after the timeout (default 30 s, maximum 300 s) and kills the whole process tree;

• appends one JSON line per command to .mcp/commands.log.

On Windows the default shell is Windows PowerShell (powershell.exe). The command is passed as a UTF-16LE -EncodedCommand, so Cyrillic and other non-ASCII text works in arguments and output. Use PowerShell syntax: Get-ChildItem, Get-Content, $env:NAME, and so on.

Background processes

For dev servers, watchers and long builds there are four more tools, enabled by the same switch:

• start_process starts a command in the background and returns an id;

• read_output returns what it has printed so far, can wait for it to finish and can clear the buffer;

• stop_process stops it and the whole process tree;

• list_processes lists the processes of this session.

Up to 8 processes can run at once (MCP_MAX_PROCESSES), each keeps at most 100000 characters of stdout and stderr (MCP_MAX_PROCESS_BUFFER), and all of them are stopped when the server exits. Starts and exits are also written to .mcp/commands.log.

The terminal is not a sandbox. Commands run with your user rights and every side effect is real — rm, git reset --hard and similar commands do what they say, and the file tools' trash and undo do not cover them. Leave the switch off unless you need it, and read a command before you approve it.

Example prompts

• "Find all *.tsx files in src."

• "Show me the project tree two levels deep."

• "Look at design/mockup.png and build the same layout."

• "Find where MCP_FILE_ROOT is used and show two lines of context."

• "In config.js replace port: 3000 with port: 8080 and debug: false with debug: true — do it in one action."

• "Replace oldName with newName in every .js file under src."

• "Zip src and README.md into release.zip."

• "Delete temp.log." → the file goes to the trash.

• "Run npm test and show me the failures." (terminal enabled)

• "Start npm run dev in the background and show its output." (terminal enabled)

• "Run git status in this folder." (terminal enabled)

• "Restore the last deletion." / "Undo the last two changes."

• "Show the trash."

• "Create docs/api.md and describe the endpoints from src/routes."

Settings (environment variables)

Security

• All paths are normalized; escaping every allowed folder is blocked.

• Root folders cannot be deleted, moved or overwritten.

• A non-empty folder can only be deleted with recursive=true.

• Overwriting or copying onto an existing file requires overwrite=true.

• The service folder .mcp is protected from changes through the tools.

• Deletion is reversible by default: the file goes to the trash.

• Archives are extracted inside the destination only; paths that try to escape it are rejected, ZIP64 and encrypted archives are not supported.

• The server never runs shell commands unless MCP_ALLOW_SHELL=1 is set. When enabled, commands run with your user rights, are limited to the allowed folders, are logged to .mcp/commands.log, and are not covered by trash or undo. Background processes are capped and stopped when the server exits.

• The UI listens on 127.0.0.1 only and requires a random token in the URL, so other devices and websites cannot control it.

If you need access to the whole disk, set MCP_ALLOW_OUTSIDE_ROOT=1. Do this consciously: Claude will be able to change any file your user has rights to.

Development

npm run inspect

Starts MCP Inspector for manual testing of the tools.

License

MIT