Desktop Commander (MCP server) — Use Cases, Install & Live Demo

Why use it

Key features

Surgical edit_block tool for diff-style edits — no whole-file rewrites
Terminal commands with timeouts and background process tracking
Configurable allowed_directories so Claude can't escape your workspace
Search across files with ripgrep-like speed
Image read support for screenshots and design files

Live Demo

What it looks like in practice

desktop-commander-mcp.replay ▶ ready

0/0

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

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

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

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

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

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

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

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

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "desktop-commander-mcp": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@wonderwhy-er/desktop-commander"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add desktop-commander-mcp -- npx -y @wonderwhy-er/desktop-commander

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use Desktop Commander

Use Claude Desktop as a free coding agent without Cursor or Claude Code

👤 Devs who want agentic coding without paying for IDE subscriptions ⏱ ~20 min beginner

When to use: You have Claude Desktop already and want it to actually edit your repo, not just paste snippets.

Prerequisites

Claude Desktop installed — Download from claude.ai/download
Working directory whitelisted — First run prompts for which directories Claude can touch

Flow

Install and lock the workspace

Install desktop-commander. Limit it to ~/Code/myproject — nothing outside.✓ Copied

→ Config shows allowed_directories restricted; tool listing appears in Claude
Drive a real change

Open ~/Code/myproject. Find every TODO comment, group by file, propose fixes for the top 5.✓ Copied

→ ripgrep-fast scan, prioritized list with line numbers
Apply with edit_block

Apply the proposed fixes using edit_block. Don't rewrite whole files — just the necessary diffs.✓ Copied

→ Each edit shows old_string/new_string blocks; clean git diff afterwards

Outcome: Claude Desktop now writes real code changes to your repo with the same quality as a paid IDE assistant.

Pitfalls

Forgot to set allowed_directories — Claude scans your home folder — Edit ~/.claude-server-commander/config.json and restart Claude Desktop

Combine with: github · filesystem

Run dev servers and capture output without blocking the chat

👤 Devs debugging multi-process setups ⏱ ~25 min intermediate

When to use: You need Claude to start a server, run tests in another terminal, and tail logs simultaneously.

Flow

Start the server in background

Start npm run dev as a background process. Show me the PID.✓ Copied

→ Process started, PID returned, output streaming captured
Run tests against it

While that's running, execute the e2e suite and surface any failures.✓ Copied

→ Tests run independently; server keeps streaming
Inspect logs on demand

Show the last 100 lines of stdout from PID 12345. Anything red?✓ Copied

→ Log slice with errors highlighted

Outcome: Multi-process debugging session orchestrated entirely from Claude.

Pitfalls

Background process keeps running after chat ends — Use kill_process tool when done, or restart Claude Desktop

Bulk refactor across hundreds of files in one session

👤 Devs doing codebase-wide migrations (e.g. rename, deprecate) ⏱ ~60 min intermediate

When to use: Your IDE assistant chokes on >50-file changes; you want one orchestrated pass.

Flow

Scope the change

Find every import of oldLib. Group by file and tell me how many changes per file.✓ Copied

→ Histogram of impact
Test on one file first

Apply the migration to the smallest-impact file as a smoke test.✓ Copied

→ Single file migrated; tests pass
Roll out in batches

Now apply to the next 20 files. After each batch, run lint and tell me if anything breaks.✓ Copied

→ Progress reports per batch with health check

Outcome: Codebase-wide migration completed with verifiable per-batch checkpoints.

Pitfalls

edit_block fails on whitespace differences — Use search-replace mode for trickier patterns; check line-ending mode

Combine with: github

Combinations

Pair with other MCPs for X10 leverage

desktop-commander-mcp + github

Local edit then PR creation

Apply the fixes via desktop-commander, then use github MCP to open a PR with a clean summary.✓ Copied

desktop-commander-mcp + filesystem

Compare different sandboxed filesystem accesses

Use filesystem MCP for read-only library scans and desktop-commander for actual project edits.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call
execute_command	command: str, timeout_ms?: int	Any shell action — git, npm, build scripts
edit_block	file_path, old_string, new_string	Surgical edits — no whole-file rewrites
read_file	path	Read source for context
write_file	path, content	New file creation
search_files	path, pattern	Find files by name/glob
search_code	pattern, path?	Content search across files
list_processes	()	See what's running in the session

Cost & Limits

What this costs to run

API quota: N/A — local
Tokens per call: Variable — long files burn tokens
Monetary: Free (MIT)
Tip: Use search_code instead of read_file when you only need a few lines

Security

Permissions, secrets, blast radius

Minimum scopes: filesystem-read filesystem-write shell-exec

Credential storage: None — all local

Data egress: None — all calls local

Never grant: Unrestricted root directory access

execute_command can run anything — keep allowed_directories tight
Don't grant access to ~/.ssh or credential dirs

Troubleshooting

Common errors and fixes

Permission denied on edit_block

Add the directory to allowed_directories in ~/.claude-server-commander/config.json

Verify: cat the config and restart Claude Desktop

Process started but no output

Use read_output with the PID; output is buffered, not streamed to chat by default

edit_block reports 'old_string not found'

Whitespace or line endings drift — re-read the file first to copy exact bytes

Alternatives

Desktop Commander vs others

Alternative	When to use it instead	Tradeoff
Claude Code (CLI)	You want first-party Anthropic agentic loop with planning	Claude Code is more polished but requires its own subscription; Desktop Commander is free
filesystem (official MCP)	Read-only or sandboxed file access without shell exec	Smaller surface, no command execution

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills