How to install DesktopCommanderMCP: Claude Code file search, terminal control and differential editing configuration

Sun, 12 Jul 2026 10:34:00 +0800

DesktopCommanderMCP is a local MCP server that allows Claude Code, Codex and other compatible clients to search for files, read and edit text, execute terminal commands and view the output of long tasks. It is suitable for scenarios where “let AI complete retrieval, modification and verification in a designated workspace”, rather than handing over the entire computer to the model unconditionally.

It appeared on GitHub Trending this week, indicating that developers are paying more attention; but it is more important to understand permissions before installation: the command will be run as the current user who started the server. Therefore, narrow down the working directory and authorization scope first, and then think about automation.

What DesktopCommanderMCP can do

According to the project description, in addition to the standard MCP file system capabilities, it supplements the following common capabilities:

Recursively search files and text content, which can be used for code base location;
Small range text replacement and multi-file editing can be used for differential modification;
Run terminal commands, stream read output, background execution and process management;
Perform paged reading of large file output to reduce the amount of content stuffed into the context at once;
Read and process common files such as CSV, JSON, Excel, PDF, DOCX, etc.;
Tool calls audit logs, command block lists, and symbolic link protection for file operations.

These capabilities do not mean that every client will display the tool in the same way, nor that all operations should be automatically approved. The more it can do, the more important it is to let the model first describe the command to be executed, the target path, and the expected changes.

Safety check before installation

Complete these items first before adding the MCP:

Install Node.js and verify that npx is available in the terminal.
Create a separate project directory for your AI work, do not initially expose it to your personal home directory, downloads directory, or configuration directory containing credentials.
Confirm the client’s permissions policy: High-risk commands, deletions, network requests, and bulk modifications should require confirmation.
Only test in trusted repositories or restorable working copies; commit important projects to Git or create backups first.
For stronger isolation, prioritize Docker and only mount folders you clearly need.

Don’t put API keys, private keys, browser profiles, cryptographic libraries, or production configuration files in freely searchable directories. DesktopCommanderMCP’s commands are executed with your user rights. MCP is not a secure sandbox.

Claude Code installation command

Run in terminal:

`1`	`claude mcp add --scope user desktop-commander -- npx -y @wonderwhy-er/desktop-commander@latest`

--scope user means adding the server to the current user scope. If you only want the current project to use it, remove --scope user and then execute it in the project directory. Restart Claude Code after installation, or confirm in the client’s MCP list that desktop-commander is connected.

The first time you use it you can give it a low risk task, for example:

Only search for TypeScript files containing TODO in the current project, list the path and line number, do not modify the file, and do not run the command.

Confirm that the file search results are as expected before allowing it to perform tests or differential edits.

Codex installation and TOML configuration

For Codex, you can run directly:

`1`	`codex mcp add desktop-commander -- npx -y @wonderwhy-er/desktop-commander@latest`

You can also write ~/.codex/config.toml manually:

1
2
3

[mcp_servers.desktop-commander]
command = "npx"
args = ["-y", "@wonderwhy-er/desktop-commander@latest"]

After manual configuration, open a new Codex session and check if the MCP is loaded. If the project only needs temporary use, give priority to project-level or session-level configuration; do not permanently expose high-privilege file tools to all projects for the debugging task of a warehouse.

How to use file search and differential editing

The value of DesktopCommanderMCP is not to “let the model directly rewrite the entire warehouse”, but to narrow the scope first and then produce reviewable changes. A safe order is:

First specify the project root directory that is allowed to be accessed.
The model is asked to first search for keywords and list hit files.
Let it read the minimum amount of relevant code and tests.
Explicitly ask to make only one logical change and show the diff.
Review the diff before allowing targeted tests to be written and run.

For example:

Search the current warehouse for the call point of createClient. List path, purpose, and test files first; do not write. Once confirmed, replace the base URL only in the file responsible for API initialization and show the differences. Do not modify the lock file or extraneous formats.

This type of directive is more controllable than “fix API configuration”: path ranges, modification targets, prohibitions, and validation actions are all clear.

How to control long commands and background processes

The tool supports command output streaming, background execution, process lists, and stopping processes, making it suitable for building, developing servers, or testing longer tasks. But long-term processes should not be left unattended.

Suggestions:

Start by running a read-only or short-lived command such as git status, a single test file, or a dry run of the build;
Set a reasonable timeout for the command, do not default to running indefinitely;
Before starting a development server, migration, or batch script, require the model to specify the port, write path, and stop method;
View the log in pages, do not fill the complete build log with the model;
After completion, confirm that the background process has exited to avoid port occupation or leaving child processes behind.

If the model proposes a command to delete, reset, overwrite, upload, deploy, or access production, it should stop at the confirmation point. Just because the tool can be executed does not mean that the operation has been authorized by the business.

When is Docker isolation suitable?

If you don’t want to install Node.js locally, or if you want to limit the visible range of files, you can use the Docker method provided by the project. The basic configuration is as follows:

{
  "mcpServers": {
    "desktop-commander-in-docker": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "mcp/desktop-commander:latest"]
    }
  }
}

This basic configuration does not mount the local directory, so the host files cannot be edited directly. When you need to operate a project, only mount a clear directory, such as a workspace, and map it to a fixed path in the container; do not mount the entire user directory, root directory, or credential directory. Docker can reduce the scope of misoperation, but the mounted directory will still be modified by commands within the container.

Troubleshooting common problems

Client does not see MCP tool

Check whether Node.js and npx can run, confirm that the configuration file is written in the location where the corresponding client actually reads it, and then restart the client or open a new session. Also check that the MCP configuration is valid JSON/TOML and that there are no conflicting server entries with the same name.

`npx` starts slowly or fails every time after installation.

First run it separately in the terminal:

`1`	`npx -y @wonderwhy-er/desktop-commander@latest`

Observe whether Node.js, the network, npm cache, or the enterprise proxy are causing the problem. Don’t attribute “client not connecting” directly to the MCP configuration; first make sure the command itself starts, then go back to the client log to check the stdio connection.

The model searched for files that should not be seen.

Stop the MCP session immediately and check the client workspace, startup directory, and Docker mount directory. Then narrow the accessible paths, move sensitive files out, and retest the read-only search. Don’t rely on “don’t look” in prompt words as a substitute for path and permission isolation.

Difference editing changes too much

First restore to the known state of Git or use the editor’s diff to undo, and then split the task into small pieces: only one file, one function, or one type of replacement is allowed at a time, and the modification plan and diff are required to be output first. For batch replacements, do a test run on a copy or a small number of files first.

Relevance to the Generic MCP Troubleshooting Article

If the problem is that the server connection fails, the configuration is not loaded, the tool call error is reported, or the client does not find MCP, first refer to [How to troubleshoot MCP tool call failure] (/en/2026/07/08/mcp-tool-call-failure-troubleshooting-faq/). This article further deals with the specific installation, file permissions, terminal operation and differential editing strategies of DesktopCommanderMCP; the two articles can be used in combination to separate “unable to connect” and “how to use it safely after connecting”.

Summary

DesktopCommanderMCP is suitable for putting file search, differential editing and terminal verification into the same workflow in Claude Code or Codex. The correct way to use it is to install in a restricted project directory first, perform a read-only search first, then review the diff, and finally allow writing and testing; long-term commands, sensitive directories and Docker mounts must have clear boundaries. This can not only maximize the efficiency of MCP, but also avoid the risk of turning local permissions into unreviewable automation.

Official warehouse: https://github.com/wonderwhy-er/DesktopCommanderMCP

AI Programming on KnightLi Blog