Desktop Commander MCP: Run Shell from Claude (2026 Guide)

TL;DR + what you actually need

The four things you’ll keep typing if you use Desktop Commander:

• NPM package: @wonderwhy-er/desktop-commander — the stdio MCP server. Runs as a local subprocess of your client.
• One-line setup: npx -y @wonderwhy-er/desktop-commander setup — writes the config entry into your client’s MCP config and you’re done. Works for Claude Desktop on macOS, Linux, and Windows out of the box.
• Repo: github.com/wonderwhy-er/DesktopCommanderMCP — MIT-licensed, maintained by Eduard Ruzga (wonderwhy-er).
• Audit log path: ~/.claude-server-commander/claude_tool_call.log — every tool call is recorded. Read it after any agentic run.

The rest of this guide walks through what each of the ~25 tools does, the install path for every client, six workflows we actually use it for, and a long security section because Desktop Commander is the MCP server you are most likely to regret misconfiguring.

What Desktop Commander actually does

Out of the box, Claude Desktop and Cursor (and many other MCP-client UIs) can read the conversation, search the web if you wire that in, and talk to other MCP servers. What they cannot do natively is execute a shell command on your machine. Desktop Commander is the wrapper that fills that gap. The MCP server runs as a local Node subprocess of your client, exposes ~25 tools, and forwards each tool call to the appropriate OS primitive: fs for filesystem, child_process for processes, plus some bespoke logic for diff-based editing and search streaming.

The mental model: Desktop Commander turns Claude into a developer sitting at your keyboard. It can ls, cat, grep, vim (via diff edits, not actual vim), run npm install, run a test suite, watch the output, kill a hung process, and try again. For the Claude-Desktop-on-its-own use case that’s a qualitative step-change — Claude Desktop is otherwise a chat window. For Claude Code, Cursor, or Codex CLI, where a shell tool already exists, Desktop Commander adds the extras: long-running interactive process control, PDF and Excel reading, an audit log of every tool call, and a fuzzy-search edit log that shows you exactly where the model’s in-place edits drifted from the file.

Eduard Ruzga released the first cut of Desktop Commander in December 2024, riding the Claude Desktop MCP wave that Anthropic kicked off a few weeks earlier. The project has grown into one of the most popular community MCP servers — referenced from Claude’s own docs, the MCP showcase pages, and the package consistently sits near the top of npm download counts for @wonderwhy-er scoped packages. The product site at desktopcommander.app hosts a managed UI on top of the same tools, but you do not need it to use the MCP server — that part is fully open source and free.

How it works (stdio shell + fs wrapper)

Desktop Commander uses the stdio transport — never the remote / Streamable-HTTP one. That is a deliberate design constraint and worth understanding before you wire it up. The MCP client (Claude Desktop, Cursor, etc.) spawns the Desktop Commander process as a local subprocess and talks to it over the process’s stdin/stdout. The server then talks to your filesystem and processes locally. Nothing about Desktop Commander is designed to be exposed over a network port.

Never expose Desktop Commander as a remote MCP server. There’s no scenario where putting a shell-and-filesystem MCP behind a public URL is the right call. The recent wave of accidentally-public MCP servers we covered in our 200,000-exposed-MCP-servers piece is the cautionary tale here — many of those exposed servers had filesystem or shell access, and several researchers found unauthenticated read/write/execute by pointing curl at them. Desktop Commander running over stdio inside Claude Desktop on your laptop is a different trust posture entirely. Keep it there.

Process model on a typical install: when Claude Desktop starts, it reads claude_desktop_config.json, sees the desktop-commander entry, and spawns node running the package’s entry point. The Node process registers ~25 tools with the MCP protocol handshake. On every tool call from the LLM the client prompts the human (you) for approval, then routes the call to the Node process, which executes the OS primitive and streams the result back. Stop Claude Desktop and the subprocess dies. Restart it and the subprocess respawns. Simple, contained, no daemon.

Install (every client)

The fastest path on any platform is the setup CLI the project ships:

npx -y @wonderwhy-er/desktop-commander setup

Run it once. It auto-detects which MCP clients are installed (Claude Desktop, Cursor, Claude Code, Codex CLI, others) and offers to write the server entry into each one’s MCP config. Pick the clients you want, restart them, and the tools show up.

For per-client config, the install panel below pulls the exact JSON / TOML / one-line CLI for every supported client straight from our catalog. Tap your client row, copy the snippet, and paste it where the panel tells you. Three of the configs are worth highlighting in prose:

• Claude Code: claude mcp add desktop-commander npx -y @wonderwhy-er/desktop-commander — registers the server at user scope. Add --scope project to write to .mcp.json at the repo root if you want the install to travel with the repo. Most teams keep this at user scope so it’s not committed.
• Cursor: open Settings → MCP → Add new global MCP server and paste the JSON snippet from the panel into ~/.cursor/mcp.json. Restart Cursor and accept the discovery prompt.
• Codex CLI: the panel emits a [mcp_servers.desktop-commander] TOML block ready to paste into ~/.codex/config.toml. Codex re-reads config on next invocation.

One-line install · Desktop Commander

Open server page

Install

Cursor

One-click install

1-Click

VS Code

One-click install

1-Click

Claude Desktop

Copy configuration

Claude Code

Copy CLI command

CLI

Gemini

Copy CLI command

CLI

Codex

Copy CLI command

CLI

Windsurf

Copy configuration

ChatGPT

Add via Settings → Connectors

M

Manual

Copy configuration

Windows-specific notes

desktop commander windows is the second-most searched Desktop Commander query we see, so this section is its own piece. The setup CLI works on Windows, but a few things bite people often enough to call out:

• Run setup from an elevated PowerShell only if you actually need it. The MCP subprocess runs as whatever user starts Claude Desktop. If you run setup as Administrator but launch Claude Desktop as your normal user, the config edits end up in the wrong profile. Run both as the same user.
• Node on PATH for the GUI launcher. Claude Desktop on Windows launches the MCP subprocess from the same process tree as the GUI, which inherits the system PATH at login. If Node was installed after you last logged in, node may not resolve. Symptom: server starts, then immediately exits with spawn node ENOENT in the logs. Fix: log out and back in, or reboot.
• PowerShell vs cmd.exe vs Git Bash. Desktop Commander’s defaultShell config setting picks the interpreter for execute_command. On Windows the default is PowerShell. If your project’s scripts assume bash semantics (heredocs, $() substitution, POSIX quoting), point defaultShell at bash.exe from Git for Windows or WSL.
• Config paths. Claude Desktop config: %APPDATA%\Claude\claude_desktop_config.json. Desktop Commander config and logs: %USERPROFILE%\.claude-server-commander\ and %USERPROFILE%\.claude-server-commander-logs\. When tools mysteriously fail, the audit log here is the first place to look.
• Long paths. Windows’ 260-char path limit catches projects with deep node_modules. Either enable long paths in the registry (LongPathsEnabled = 1) or move the project to a shorter root like C:\dev\.

The full client catalogue with current config paths lives at mcp.directory/clients — that’s the canonical reference. For Claude Code specifically, see claude-code; for Cursor see cursor; Codex CLI is at codex; Claude Desktop is at claude-desktop.

Every tool, walked through

Desktop Commander exposes around two dozen tools across six families: config, processes, filesystem reads, filesystem writes, search, and edit. Names and signatures below are taken straight from the project README — the current set as of May 2026.

Config tools

• get_config — Returns the full server config JSON. Useful sanity check after install: “show me the current Desktop Commander config” and verify allowedDirectories and blockedCommands match what you intended.
• set_config_value — Sets a single config key. Used by the agent to flip flags at runtime. We prefer editing the config file directly so changes are auditable in git; treat this tool as something to block in your blockedCommands in shared/team installs.

Process tools

• start_process — Launches a program and waits for readiness. The smart upgrade over a raw execute_command for long-running things like dev servers and watchers. Returns a process handle the agent can talk to.
• interact_with_process — Sends input to a running process. This is how the agent answers a Y/N prompt from npm init, responds to a REPL, or feeds stdin to a script.
• read_process_output — Reads stdout/stderr from a running process. The agent can poll for output while a build is happening and react when something fails.
• force_terminate — Kills a terminal session managed by Desktop Commander.
• list_sessions — Lists active sessions. Lets the agent clean up after itself, or find a process it started earlier.
• list_processes — System-wide process list. Equivalent of ps aux with extra metadata.
• kill_process — Terminates a process by PID. Useful for “dev server is stuck, kill it and restart” flows.

Filesystem read tools

• read_file — Reads a local file, or a URL, or an Excel file, or a PDF. Pagination is built in (positive and negative offsets, like tail -n). The PDF and Excel handling is surprisingly useful and is one of the tools you don’t get from Claude Code’s built-in read.
• read_multiple_files — Reads several files in one call. Saves round-trips when the agent needs to compare implementations across a small codebase.
• list_directory — Recursive directory listing with a depth control. The agent uses this to build a project map before deciding where to edit.
• get_file_info — Metadata only: size, mtime, permissions. The agent calls this before deciding whether to re-read a large file or use a cached previous read.

Filesystem write tools

• write_file — Writes content to a file. Rewrite and append modes. The big footgun here is full-file rewrites for files where the agent only intended to change a few lines — always prefer edit_block for surgical edits.
• write_pdf — Generates a PDF from markdown. Niche but it’s there.
• create_directory — mkdir -p equivalent.
• move_file — Move or rename. Handles cross-device moves gracefully.

Search and edit tools

• start_search — Streaming search across the filesystem by filename or file content. Returns a search handle. Built for big repos where you want results to start appearing immediately rather than waiting for a full scan.
• get_more_search_results — Pagination for the above. The agent calls this in a loop while results are still useful.
• stop_search — Cancels a running search. Frees resources when the agent has what it needs.
• list_searches — Active searches. Lets the agent reconnect to a long-running search.
• edit_block — The diff-style editor. Takes a target file, an “old” text block, and a “new” text block, and replaces the old with the new in place. If the old block doesn’t match exactly, Desktop Commander’s fuzzy-search logs the near-misses to fuzzy-search.log so you can see why an edit failed.

Telemetry and feedback

• get_usage_stats, get_recent_tool_calls, give_feedback_to_desktop_commander — these expose Desktop Commander’s own usage history and a feedback channel to the maintainers. Usually fine to leave on; if you’re in a high-confidentiality environment, add them to blockedCommands.

Recipes

Six workflows we actually use Desktop Commander for. Each assumes the server is installed at user scope and you’ve disabled any auto-approve settings on the client.

Recipe 1 — Refactor a project across many files

The classic. Prompt: “Rename getUserById to findUser across the whole repo, including tests and imports. Use Desktop Commander to find all references first, then edit_block each one.” The agent runs start_search against the repo, builds the list of references, and walks each one with edit_block. You approve each edit from your client’s UI. Faster than a global find-replace because the agent knows when to skip comments and strings.

Recipe 2 — Run a test suite and fix what fails

Prompt: “Run npm test with Desktop Commander, watch the output, and for each failing test, open the file, read the failing assertion, propose a fix, and apply it with edit_block.” Uses start_process + watching read_process_output + read_file + edit_block in a loop. This is one of the strongest agent loops Desktop Commander enables. Approve each edit; do not let the agent auto-apply.

Recipe 3 — Git operations in natural language

Prompt: “Stage the changes in src/lib/, show me the diff, and if it looks right, commit with message ‘refactor: extract data-source layer’.” The agent runs git add, git diff --cached, and asks you to confirm before git commit. We do not recommend ever approving an auto-git push for the agent — push is the line where a mistake leaves your machine and becomes a teammate’s problem.

Recipe 4 — Debug a crashed background process

Your dev server crashed silently. Prompt: “List node processes, grep for the dev server, and tell me whether it’s still alive. If it’s dead, find the latest log entry that mentions error and explain it.” Uses list_processes, then start_search on the log directory, then read_file on the relevant log lines. The agent ends up in roughly the same place you’d arrive after five minutes of poking at the terminal.

Recipe 5 — One-shot data analysis from a CSV / Excel file

Drop an Excel file in a directory and prompt: “Read sales-may-2026.xlsx with Desktop Commander, find the top 5 revenue accounts for the month, and write the summary to reports/may-2026.md.” read_file handles Excel natively, the agent does the analysis in conversation, then write_file drops the markdown.

Recipe 6 — Initial project scaffold

Prompt: “Create a Next.js 15 project in ~/dev/new-app with TypeScript, Tailwind, and shadcn/ui, then install lucide-react and @vercel/analytics.” The agent runs npx create-next-app, interacts with the prompts via interact_with_process, then runs the follow-up npm install commands. Saves the ten minutes you’d otherwise spend mashing through the CLI yourself. Pair with Context7 for version-correct boilerplate.

Security: the section that matters

We’ll repeat the framing once because it matters: Desktop Commander has the same blast radius as your user shell. Anything you can do at a terminal, the model can do via Desktop Commander. Anything the model does, it can do without you stopping to think about whether it’s a good idea. The combination is what makes this server uniquely risky among MCP servers. Here’s how we actually run it.

1. Never disable the per-tool approval prompt

Every modern MCP client surfaces an approval modal on each tool call: “the agent wants to run npm install lodash, approve or deny?”. Some clients have a setting that lets you skip the prompt for “trusted” tools or disable approvals globally — Claude Code calls it --dangerously-skip-permissions; some Cursor builds have an “auto-approve all” toggle; some agentic CLIs have it on by default. Do not pair any of these with Desktop Commander. The approval loop is the single point of defence between the model’s reasoning and your filesystem. Removing it is the most common way Desktop Commander users have ended up with deleted directories, force- pushed branches, or worse.

2. Configure blockedCommands aggressively

Desktop Commander’s config supports a blockedCommands array — commands matching any pattern in it are rejected server-side before they reach the OS. A reasonable starter list:

{
  "blockedCommands": [
    "rm -rf /",
    "rm -rf ~",
    "rm -rf $HOME",
    "dd if=",
    "mkfs",
    ":(){:|:&};:",
    "curl * | sh",
    "curl * | bash",
    "wget * | sh",
    "wget * | bash",
    "shutdown",
    "reboot",
    "sudo rm",
    "git push --force",
    "git push -f",
    "git reset --hard"
  ]
}

The list is not a moat. A model that wants to bypass it can echo the command into a script and execute the script; can pipe through base64; can write a node script that calls fs.rmSync directly. The list is a speed bump for accidents, not a sandbox. Pair it with the next item.

3. Scope filesystem reach with allowedDirectories

Desktop Commander’s filesystem tools (read, write, edit, search) honour an allowedDirectories config setting. Set it to the project root and nothing more:

{
  "allowedDirectories": [
    "~/dev/my-project",
    "~/Downloads"
  ]
}

Anything outside is rejected. The maintainer explicitly notes that this scoping applies to the filesystem tools but does not stop a shell command from doing whatever it wants — a cat ~/.ssh/id_rsa via execute_command bypasses allowedDirectories because the shell can cat anywhere your user can read. So this scoping is useful but not sufficient. Combine with the next item.

4. Run inside Docker for anything untrusted

The repo ships install-docker.sh / install-docker.ps1 scripts that put Desktop Commander inside a sandboxed container with a mounted project directory. Inside the container, the shell can do whatever it wants — but “whatever it wants” is scoped to the container, not your real machine. Use this if:

• You’re running an autonomous agent loop where you can’t approve every call by hand.
• The prompt source is untrusted — anything pulled from a website, a Reddit thread, a GitHub issue, an email.
• You’re experimenting with prompt-injection hardening and want a blast-radius cap.
• Multiple MCP servers are wired up together — the attack surface from prompt injection across servers is real.

5. Read the audit log after every agentic run

Every tool call Desktop Commander processes is written to ~/.claude-server-commander/claude_tool_call.log with timestamp, tool name, and arguments. The log rotates at 10MB. Make this a habit: after any multi-step agentic run, scan the tail of the log. You’ll spot patterns that the per-call approval prompt missed — for example, the agent calling read_file on more files than it needed, or doing extra list_directory calls in directories outside the project. fuzzy-search.log separately captures every near-miss edit_block so you can see when an edit failed because the source file drifted from what the model expected.

6. Never expose Desktop Commander remotely

Worth saying twice. Desktop Commander uses stdio. The project does not ship a remote / HTTP transport. If you find yourself wanting to expose Desktop Commander over a network — even “just to my own VPS for experiments” — stop. That’s the pattern that landed 200,000 MCP servers in the exposed-servers analysis we covered earlier this year. If you need remote shell access, use a remote shell tool (SSH) with proper auth, not a remote MCP server with shell tools wrapped inside it.

7. Stage your trust gradually

For a new install, walk through the first dozen tool calls in read-only mode mentally: deny any write_file, edit_block, execute_command for the first session and watch what the agent actually wants to do. The pattern of what gets requested tells you whether the prompts you’re feeding it are appropriately scoped. Then graduate to approving writes one at a time. Skip this and the first time you see the agent propose a git push --force will be the time you’ve already approved 18 things in a row and your finger clicks “approve” before your brain catches up.

Pricing & license

The Desktop Commander MCP server is free and MIT-licensed. The full license text lives at github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/LICENSE. MIT means you can use it commercially, fork it, redistribute it, no obligations beyond preserving the license notice.

Separately, the team behind Desktop Commander runs a managed product at desktopcommander.app — an AI-with-shell-tools UI that uses the same primitives under the hood. That product has a free tier (100 messages per week) and a paid tier ($7/month for no message cap). The product is independent of the open-source MCP server; you do not need it to use Desktop Commander inside Claude Desktop, Cursor, or any other MCP client. We mention it only because people find the product first and then wonder if they need to pay anything to use the MCP — they don’t.

Troubleshooting

When NOT to use Desktop Commander

Honest section. Desktop Commander is the wrong tool for more situations than you might think.

• You only need scoped read-only repo browsing. If the goal is “let Claude look at this codebase and answer questions” without writes, DeepWiki or a GitHub MCP server is safer. Both are read-only by design; Desktop Commander is not.
• You only need documentation lookup. Context7 ships up-to-date library docs with no shell or filesystem access at all. If the agent is wrong because it doesn’t know the latest API, that’s a docs problem, not a shell problem.
• You’re running an autonomous agent with no human in the loop. Don’t do this with raw Desktop Commander. Put it in Docker, scope allowedDirectories hard, and even then assume the agent will eventually do something surprising.
• Multi-user / shared dev environments. Desktop Commander assumes the user running it is the same user who approves each tool call. On shared hosts where multiple developers SSH in, the tool approvals get murky fast. Keep it on your laptop.
• Production servers. Self-explanatory but worth saying. Production is not a place to run experimental MCP servers with shell access. If you want LLM-powered ops in production, build a custom MCP server with the specific, audited, scoped tools you need — not the kitchen sink.

FAQ

Sources

• Desktop Commander repository & README: github.com/wonderwhy-er/DesktopCommanderMCP (MIT, maintained by Eduard Ruzga / wonderwhy-er)
• NPM package: @wonderwhy-er/desktop-commander
• Product site: desktopcommander.app
• Maintainer post-mortem on the launch: From 80K Views to Hacker News and Product Hunt by Eduard Ruzga
• Catalog entry: mcp.directory/servers/desktop-commander