---
title: "Desktop Commander MCP: Terminal and File Access for Claude"
url: "https://mcpshelf.co/servers/desktop-commander"
description: "Desktop Commander gives Claude and other MCP clients a terminal, file search and diff-based edits on your machine. Config, what it can reach, our test."
updated: "2026-10-27"
site: "MCP Shelf"
---

# Desktop Commander

> A terminal, file search and surgical file edits for your assistant.

Source: https://mcpshelf.co/servers/desktop-commander  
Markdown: https://mcpshelf.co/servers/desktop-commander.md  
Generated: 2026-11-22T22:03:05.225Z

## Facts

- **Name:** Desktop Commander
- **Tagline:** A terminal, file search and surgical file edits for your assistant.
- **Description:** Desktop Commander is an open-source MCP server that gives AI assistants such as Claude a terminal, file search and precise, block-by-block file editing on your own computer.
- **Repository:** https://github.com/wonderwhy-er/DesktopCommanderMCP
- **Package:** @wonderwhy-er/desktop-commander 0.3.1 (npm)
- **Install:** `npx @wonderwhy-er/desktop-commander@latest setup`
- **Transport:** stdio (local)
- **Auth:** No required keys or settings listed
- **Tools exposed:** 25: `get_config`, `set_config_value`, `read_file`, `read_multiple_files`, `write_file`, `write_pdf`, `create_directory`, `list_directory`, `move_file`, `start_search`, `get_more_search_results`, `stop_search`, `list_searches`, `get_file_info`, `edit_block`, `start_process`, `read_process_output`, `interact_with_process`, `force_terminate`, `list_sessions`, `list_processes`, `kill_process`, `get_usage_stats`, `get_recent_tool_calls`, `give_feedback_to_desktop_commander`
- **Category:** Developer tools (https://mcpshelf.co/categories/developer-tools)
- **Stats:** 10.2K GitHub stars, 394.7K downloads a week, last commit 28 Oct 2026, 1 upvote on MCP Shelf
- **Install check:** Started in our test
- **Listed:** 2026-10-26
- **Page updated:** 2026-10-27

## Full description

### What is Desktop Commander?

**Desktop Commander is an open-source MCP server that gives AI assistants such as Claude a terminal, file search and precise, block-by-block file editing on your own computer.**

Desktop Commander turns a chat assistant into something closer to a coding agent: it can run shell commands, keep long-running processes going, search across folders and edit files by replacing exact blocks of text instead of rewriting whole files.

It runs with your user account, so it can do anything you can do in a terminal. That is the point, and also the reason to add it to a client you watch rather than one that runs unattended.

|  |  |
| --- | --- |
| Made by | Eduard Ruzga (wonderwhy-er) and contributors |
| GitHub | https://github.com/wonderwhy-er/DesktopCommanderMCP |
| Licence | MIT |
| npm package | [@wonderwhy-er/desktop-commander](https://www.npmjs.com/package/@wonderwhy-er/desktop-commander) 0.3.1 (22 Oct 2026) |
| GitHub stars | 10.2K |
| Downloads | 394.7K a week |
| Last commit | 28 Oct 2026 |
| Tools | 25 |
| Runs on | Your computer |
| Install check | Started in our test |
| Category | [Developer tools](https://mcpshelf.co/categories/developer-tools) |
| Works with | Claude Code, Cursor, Claude Desktop, VS Code, Codex, Windsurf, ChatGPT |
| Setup checked | 27 Oct 2026 |
| Page updated | 27 Oct 2026 |

**Our check:** We ran this exact config on 26 Oct 2026: it started and answered with 25 tools.

#### Try asking Desktop Commander

- "Find every TODO in this project and list them by file."
- "Run the test suite and tell me which tests failed and why."
- "In config.yaml, change the port from 3000 to 8080 without touching anything else."

#### MCP Shelf take

> We started Desktop Commander on our own test machine on 26 Oct 2026 and it answered with 25 tools. 13 of the 25 only read; the other 12 can change things. Every tool comes with a useful description, all of them say whether they change things, and the tool list costs about 10,800 tokens of context before you ask a thing. It sits 7th of 24 in its category on our shelf by GitHub stars (10.2K, with 394.7K downloads a week).

— MCP Shelf tests (numbers from our own runs), tested on 26 Oct 2026

### What tools does Desktop Commander have?

We listed 25 tools on 26 Oct 2026. 13 only read; the rest can change things or run commands.

| Tool | Kind | What it is for |
| --- | --- | --- |
| `get_config` | reads | Shows the current settings: allowed folders, blocked commands, shell and line limits. |
| `set_config_value` | changes | Changes one setting, such as the allowed folders or the default shell. |
| `read_file` | reads | Reads a text file, Excel workbook, PDF or web address, a chunk of lines or pages at a time. |
| `read_multiple_files` | reads | Reads several files in one go. |
| `write_file` | changes | Writes or appends to a file, in chunks of 50 lines by default, including Excel data. |
| `write_pdf` | changes | Builds a PDF from Markdown, or adds and removes pages in an existing one. |
| `create_directory` | changes | Makes a folder, including any missing parent folders. |
| `list_directory` | reads | Lists the files and folders under a path, two levels deep by default. |
| `move_file` | changes | Moves or renames a file or folder. |
| `start_search` | reads | Searches file names or file contents across a folder and streams back matches. |
| `get_more_search_results` | reads | Pages through the results of a search that is still running. |
| `stop_search` | changes | Cancels a running search. |
| `list_searches` | reads | Shows which searches are still running. |
| `get_file_info` | reads | Reports a file's size, dates and permissions, plus sheet names for Excel files. |
| `edit_block` | changes | Swaps an exact piece of text in a file for new text, or updates a range of cells in an Excel sheet. |
| `start_process` | runs | Starts a terminal command and notices when it is waiting for input. |
| `read_process_output` | reads | Collects the latest output from a command that is still running. |
| `interact_with_process` | runs | Types input into a running program, such as a Python or database prompt, and returns its reply. |
| `force_terminate` | changes | Stops a terminal session that has hung or is no longer needed. |
| `list_sessions` | reads | Lists the terminal sessions it has open. |
| `list_processes` | reads | Lists what is running on the computer, with memory and CPU use. |
| `kill_process` | runs | Ends a process on your computer by its process id. |
| `get_usage_stats` | reads | Shows how often you have used each tool. |
| `get_recent_tool_calls` | reads | Lists the last tool calls with their inputs and outputs, useful after a chat is cut off. |
| `give_feedback_to_desktop_commander` | changes | Opens the project's feedback form in your browser. |

#### How clearly it describes its tools

25 of 25 tools have a description and 25 of 25 say whether they change things. The tool list takes at least ~10,800 tokens of context. Every tool says whether it only reads or can change things, so a client can ask before the risky ones. The tool list is large: switch off the tools you do not use if your client allows it.

### How do I install Desktop Commander?

#### Install steps from the Desktop Commander README

Copied from the project's [README on GitHub](https://github.com/wonderwhy-er/DesktopCommanderMCP#readme) on 20 Nov 2026 under its MIT licence.

##### Install in Claude Desktop

Desktop Commander offers multiple installation methods for Claude Desktop.

> **📋 Update & Uninstall Information:** Options 1, 2, 3, 4, and 6 have automatic updates. Option 5 requires manual updates. See below for details.

**Option 1: Install through npx ⭐ Auto-Updates (Requires Node.js)**

Just run this in terminal:

```
npx @wonderwhy-er/desktop-commander@latest setup
```

For debugging mode (allows Node.js inspector connection):

```
npx @wonderwhy-er/desktop-commander@latest setup --debug
```

**Command line options during setup:**

- `--debug`: Enable debugging mode for Node.js inspector
- `--no-onboarding`: Disable onboarding prompts for new users

Restart Claude if running.

**✅ Auto-Updates:** Yes - automatically updates when you restart Claude
**🔄 Manual Update:** Run the setup command again
**🗑️ Uninstall:** Run `npx @wonderwhy-er/desktop-commander@latest remove`

**Option 2: Using bash script installer (macOS) ⭐ Auto-Updates (Installs Node.js if needed)**

```
curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install.sh | bash
```

This script handles all dependencies and configuration automatically.

**✅ Auto-Updates:** Yes
**🔄 Manual Update:** Re-run the bash installer command above
**🗑️ Uninstall:** Run `npx @wonderwhy-er/desktop-commander@latest remove`

**Option 3: Installing via Smithery ⭐ Auto-Updates (Requires Node.js)**

1. **Visit:** [https://smithery.ai/server/@wonderwhy-er/desktop-commander](https://smithery.ai/server/@wonderwhy-er/desktop-commander)
2. **Login to Smithery** if you haven't already
3. **Select your client** (Claude Desktop) on the right side
4. **Install with the provided key** that appears after selecting your client
5. **Restart Claude Desktop**

**✅ Auto-Updates:** Yes - automatically updates when you restart Claude
**🔄 Manual Update:** Visit the Smithery page and reinstall

**Option 4: Add to claude_desktop_config manually ⭐ Auto-Updates (Requires Node.js)**

Add this entry to your claude_desktop_config.json:

- On Mac: `~/Library/Application Support/Claude/claude_desktop_config.json`
- On Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- On Linux: `~/.config/Claude/claude_desktop_config.json`

```
{
  "mcpServers": {
    "desktop-commander": {
      "command": "npx",
      "args": [
        "-y",
        "@wonderwhy-er/desktop-commander@latest"
      ]
    }
  }
}
```

Restart Claude if running.

**✅ Auto-Updates:** Yes - automatically updates when you restart Claude
**🔄 Manual Update:** Run the setup command again
**🗑️ Uninstall:** Run `npx @wonderwhy-er/desktop-commander@latest remove` or remove the entry from your claude_desktop_config.json

**Option 5: Checkout locally ❌ Manual Updates (Requires Node.js)**

```
git clone https://github.com/wonderwhy-er/DesktopCommanderMCP.git
cd DesktopCommanderMCP
npm run setup
```

Restart Claude if running.

The setup command will install dependencies, build the server, and configure Claude's desktop app.

**❌ Auto-Updates:** No - requires manual git updates
**🔄 Manual Update:** `cd DesktopCommanderMCP && git pull && npm run setup`
**🗑️ Uninstall:** Run `npx @wonderwhy-er/desktop-commander@latest remove` or remove the cloned directory and MCP server entry from Claude config

**Option 6: Docker Installation 🐳 ⭐ Auto-Updates (No Node.js Required)**

Perfect for users who want isolation or don't have Node.js installed. Runs in a sandboxed Docker container with a persistent work environment.

**Prerequisites:** [Docker Desktop](https://www.docker.com/products/docker-desktop/) installed **and running**, Claude Desktop app installed.

**macOS/Linux:**

```
bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh)
```

**Windows PowerShell:**

```
iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.ps1'))
```

The installer will check Docker, pull the image, prompt for folder mounting, and configure Claude Desktop.

**Docker persistence:** Your tools, configs, work files, and package caches all survive restarts.

**Manual Docker Configuration**

**Basic setup (no file access):**

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

**With folder mounting:**

```
{
  "mcpServers": {
    "desktop-commander-in-docker": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/username/Desktop:/mnt/desktop",
        "-v", "/Users/username/Documents:/mnt/documents",
        "mcp/desktop-commander:latest"
      ]
    }
  }
}
```

**Advanced folder mounting:**

```
{
  "mcpServers": {
    "desktop-commander-in-docker": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "dc-system:/usr",
        "-v", "dc-home:/root", 
        "-v", "dc-workspace:/workspace",
        "-v", "dc-packages:/var",
        "-v", "/Users/username/Projects:/mnt/Projects",
        "-v", "/Users/username/Downloads:/mnt/Downloads",
        "mcp/desktop-commander:latest"
      ]
    }
  }
}
```

**Docker Management Commands**

**macOS/Linux:**

```
# Check status
bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh) --status

# Reset all persistent data
bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh) --reset
```

**Windows PowerShell:**

```
# Check status
$script = (New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.ps1'); & ([ScriptBlock]::Create("$script")) -Status

# Reset all data
$script = (New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.ps1'); & ([ScriptBlock]::Create("$script")) -Reset

# Show help
$script = (New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.ps1'); & ([ScriptBlock]::Create("$script")) -Help
```

**Troubleshooting:** Reset and reinstall from scratch:

```
bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh) --reset && bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh)
```

**✅ Auto-Updates:** Yes - `latest` tag automatically gets newer versions
**🔄 Manual Update:** `docker pull mcp/desktop-commander:latest` then restart Claude

##### Security

- ✅ The Remote Device only accepts commands while it is running
- ✅ Commands execute locally under your user permissions
- ✅ Secure OAuth authentication and encrypted communication channel

#### What you need first

- Node.js 18 or newer
- Nothing else: no account or key

#### Fastest way: one command

```bash
npx @wonderwhy-er/desktop-commander@latest setup
```

This adds Desktop Commander to Claude Desktop and keeps it updated each time Claude restarts. Restart Claude afterwards. To undo it, run the same command with remove in place of setup.

#### Claude Code

Where: Your terminal

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

--scope user makes it available in every project. Leave it out to add it to the current project only.

#### Cursor

Where: ~/.cursor/mcp.json, or .cursor/mcp.json in a project

```json
{
  "mcpServers": {
    "desktop-commander": {
      "command": "npx",
      "args": [
        "-y",
        "@wonderwhy-er/desktop-commander@latest"
      ]
    }
  }
}
```

#### Claude Desktop

Where: claude_desktop_config.json (Settings → Developer → Edit Config)

```json
{
  "mcpServers": {
    "desktop-commander": {
      "command": "npx",
      "args": [
        "-y",
        "@wonderwhy-er/desktop-commander@latest"
      ]
    }
  }
}
```

Or let it write this entry for you: run npx @wonderwhy-er/desktop-commander@latest setup in a terminal, then restart Claude. The same command with remove takes it out again.

#### VS Code

Where: .vscode/mcp.json in your project

```json
{
  "servers": {
    "desktop-commander": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@wonderwhy-er/desktop-commander@latest"
      ]
    }
  }
}
```

You can also put it in your User Settings JSON instead of the project file. It runs in Copilot's Agent mode.

#### Codex

Where: ~/.codex/config.toml, shared by the Codex CLI, IDE extension and ChatGPT desktop app

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

Or run: `codex mcp add desktop-commander -- npx -y @wonderwhy-er/desktop-commander@latest`

#### Windsurf

Where: ~/.codeium/windsurf/mcp_config.json

```json
{
  "mcpServers": {
    "desktop-commander": {
      "command": "npx",
      "args": [
        "-y",
        "@wonderwhy-er/desktop-commander@latest"
      ]
    }
  }
}
```

#### ChatGPT

Where: Your terminal, then mcp.desktopcommander.app

```
npx @wonderwhy-er/desktop-commander@latest remote
```

ChatGPT cannot start a local server, so the project offers a remote device mode: run this on your computer, finish the sign-in in your browser, then connect ChatGPT at mcp.desktopcommander.app. Commands still run on your machine, and only while that terminal is open.

Checked against the project's own install docs on 27 Oct 2026: https://github.com/wonderwhy-er/DesktopCommanderMCP#readme

### How do I configure Desktop Commander?

| Setting | Kind | Required | What it does |
| --- | --- | --- | --- |
| `allowedDirectories` | config | no | Folders the file tools may use. An empty list means the whole disk. Terminal commands are not limited by it. Example: `["/Users/you/projects"]` |
| `blockedCommands` | config | no | Shell commands it refuses to run. Example: `["rm", "sudo"]` |
| `defaultShell` | config | no | The shell used for commands. Example: `/bin/zsh` |
| `fileReadLineLimit` | config | no | Most lines returned by one read. Defaults to 1000. |
| `fileWriteLineLimit` | config | no | Most lines written in one call. Defaults to 50, which nudges the model into small, recoverable edits. Example: `1000` |
| `telemetryEnabled` | config | no | Set to false to stop the pseudonymous usage data it sends. No file contents or paths are included either way. Example: `false` |

### What can Desktop Commander read and change?

**It can read**

- Files and folders on your computer, inside allowedDirectories for file tools
- Running processes and their output
- Web pages, Excel files and PDFs you point it at

**It can change**

- Writes, edits, moves and creates files and folders
- Runs any terminal command your user account can run
- Can kill processes

**Safer setup:** Run the Docker version for real isolation. The project says folder limits and blocked commands can be bypassed, for example through symlinks or command substitution.

### Good for

- Using Claude Desktop as a coding agent without a separate IDE
- Running builds, tests and scripts and reading the output
- Large refactors where small targeted edits beat full-file rewrites

### Desktop Commander not working? Common fixes

**The agent changes its own settings to get around a limit**
Change settings in a separate chat from the one where you work, then check them with get_config.

**Writes stop part way through a file**
That is fileWriteLineLimit at work. Let it continue in chunks, or raise the limit with set_config_value.

**Claude Desktop will not start after removing it**
Restore the config backup the uninstaller made, or fix the JSON in claude_desktop_config.json by hand.

### What are the alternatives to Desktop Commander?

| Server | What it does | Tools | Runs on | Licence | Stars |
| --- | --- | --- | --- | --- | --- |
| [Desktop Commander](https://mcpshelf.co/servers/desktop-commander) | A terminal, file search and surgical file edits for your assistant. | 25 | Your computer | MIT | 10.2K |
| [Serena](https://mcpshelf.co/servers/serena) | IDE-style "find symbol" and "edit symbol" for an agent, backed by language servers. | 3 (REPL) | Your computer | GPL-3.0 | 30.8K |
| [Context7](https://mcpshelf.co/servers/context7) | Pulls current, version-specific library docs into the conversation. | 2 | Your computer or hosted | MIT | 63.8K |
| [GitHub](https://mcpshelf.co/servers/github) | GitHub's own server for repos, issues, pull requests and Actions. | 46 | Hosted or your computer | MIT | 34K |
| [MCP Inspector](https://mcpshelf.co/servers/mcp-inspector) | The official debugging UI for MCP servers. Not a server you add to a client. | Test client | Your computer | MIT / Apache-2.0 | 11.2K |
| [XcodeBuildMCP](https://mcpshelf.co/servers/xcodebuildmcp) | Build, run and test iOS and macOS apps, and drive simulators, from an agent. | 24 | Your computer | MIT | 6.5K |

### Desktop Commander FAQ

#### How do I install Desktop Commander in Claude Desktop?

The quickest way is to run npx @wonderwhy-er/desktop-commander@latest setup in a terminal and restart Claude; it adds the entry to claude_desktop_config.json for you. You can also paste the config by hand, use the macOS bash installer, or use the Docker installer if you do not have Node.js.

#### How do I add Desktop Commander to Claude Code?

Run claude mcp add --scope user desktop-commander -- npx -y @wonderwhy-er/desktop-commander@latest. With --scope user it loads in every project; without it, only in the folder you ran it from. Check it connected with /mcp inside Claude Code.

#### Does Desktop Commander work with ChatGPT?

Yes, through its remote device mode. You run npx @wonderwhy-er/desktop-commander@latest remote on your own computer, sign in, and connect ChatGPT (or Claude on the web) at mcp.desktopcommander.app. The commands still execute locally, and only while that process is running.

#### Is Desktop Commander safe to use?

It acts with your full user account: it can run any terminal command, edit or delete files and kill processes. The allowedDirectories and blockedCommands settings help, but the project itself warns they can be bypassed, so use the Docker install when you want real isolation and keep tool approvals on.

#### Is Desktop Commander free?

Yes. It is open source under the MIT licence and needs no account or API key. It does send pseudonymous usage statistics by default, which you can switch off by setting telemetryEnabled to false.

#### How do I update or uninstall Desktop Commander?

The npx, bash, Smithery, manual-config and Docker installs fetch the latest version each time Claude restarts. A git checkout needs git pull and npm run setup. To remove it, run npx @wonderwhy-er/desktop-commander@latest remove, or delete its entry from your client config.

#### Why does Desktop Commander stop writing part way through a file?

That is the fileWriteLineLimit setting, 50 lines per call by default, which keeps edits small and easy to recover from. The assistant is expected to carry on in further chunks. If you prefer bigger writes, raise the limit with set_config_value in a separate chat.

#### Can Desktop Commander read Excel, PDF and Word files?

Yes. Its read_file tool opens Excel workbooks, PDFs and .docx files as well as plain text, write_pdf builds a PDF from Markdown, and edit_block can change a range of cells in a spreadsheet, so you do not need a separate Office server for everyday work.

#### Desktop Commander or Serena: which do I need?

They do different jobs. Desktop Commander gives the assistant a terminal and general file access, which is what Claude Desktop lacks. Serena adds symbol-level code navigation and editing on top of tools you already have. Coding agents like Claude Code often use Serena alone; chat apps benefit most from Desktop Commander.

#### How do I add Desktop Commander to Cursor?

In ~/.cursor/mcp.json, or .cursor/mcp.json for one project, add an entry named desktop-commander that runs npx -y @wonderwhy-er/desktop-commander@latest. Save, and the tools show up in Agent chat.

#### Can I use Desktop Commander in VS Code?

Yes, through GitHub Copilot. In .vscode/mcp.json, add a server named desktop-commander with type stdio that runs npx -y @wonderwhy-er/desktop-commander@latest. You can also put it in your User Settings JSON instead of the project file. It runs in Copilot's Agent mode.

#### Does Desktop Commander work with Codex?

Yes. Run codex mcp add desktop-commander -- npx -y @wonderwhy-er/desktop-commander@latest in a terminal, or add an [mcp_servers.desktop-commander] table to ~/.codex/config.toml, which the Codex CLI and IDE extension share.

Full docs on GitHub: https://github.com/wonderwhy-er/DesktopCommanderMCP

## Notes for agents

Fetch these instead of parsing the HTML page:

- llms.txt: https://mcpshelf.co/llms.txt
- llms-full.txt: https://mcpshelf.co/llms-full.txt
- ai.txt: https://mcpshelf.co/ai.txt
- Full catalog (.md): https://mcpshelf.co/catalog.md
- API spec: https://mcpshelf.co/openapi.json
- MCP server: https://mcpshelf.co/mcp
- MCP manifest: https://mcpshelf.co/.well-known/mcp.json
- Developer docs: https://mcpshelf.co/developers

MCP endpoint (Streamable HTTP, no key): https://mcpshelf.co/mcp. REST API: https://mcpshelf.co/api/v1.

