Set Up Desktop Commander for Claude: Full Guide

By Yanni Papoutsis | 5 min read | 2026-06-25

TL;DR: Desktop Commander is an MCP server that gives Claude shell command execution, file read/write/edit, process management, and directory operations on your local machine. It is one of the most useful MCP servers for development workflows because it lets Claude run bash commands, edit files, install packages, and search code directly without you copying and pasting between windows. This guide covers installation, configuration, permission management, and effective usage patterns.

What Desktop Commander Does

Without Desktop Commander, Claude can only interact with files you explicitly paste into the conversation. With it, Claude can:

Execute shell commands (ls, grep, git, npm, python, etc.)
Read and write files anywhere on your filesystem (with your permission)
Edit specific blocks of code in existing files
Search file contents with ripgrep
List and manage running processes
Create and manage directories
Run long-running processes in the background and read their output

This transforms Claude from a chatbot into a genuine development agent that can navigate, read, and modify your codebase.

Installation

Option A: npx (no install, always latest)

npx @desktop-commander/mcp-server --help

Option B: Global install

npm install -g @desktop-commander/mcp-server

Verify:

desktop-commander --version

Configuration

Open or create your Claude MCP configuration file:

macOS: ~/.claude/mcp_servers.json

Add the Desktop Commander entry:

{
  "mcpServers": {
    "Desktop_Commander": {
      "command": "npx",
      "args": ["-y", "@desktop-commander/mcp-server"],
      "env": {}
    }
  }
}

If you installed globally:

{
  "mcpServers": {
    "Desktop_Commander": {
      "command": "desktop-commander",
      "args": [],
      "env": {}
    }
  }
}

Restart Claude Code / Cowork after editing the config file.

Verifying the Connection

In a new Claude session, run:

Use Desktop Commander to run `pwd` and tell me the current working directory.

If Claude returns a path, Desktop Commander is connected. If it says the tool is unavailable, check the config file syntax and restart Claude.

Key Tools Available

Tool	What It Does
`start_process`	Run a shell command; returns output
`read_output`	Read stdout from a running process
`read_file`	Read a file's contents
`write_file`	Write or overwrite a file
`edit_block`	Find-and-replace a specific block of code in a file
`list_directory`	List contents of a directory
`create_directory`	Create a new directory
`move_file`	Rename or move a file
`get_file_info`	Get file metadata (size, modified date, type)
`list_processes`	List running processes
`kill_process`	Terminate a process by PID
`start_search`	Search file contents with ripgrep
`get_config`	View Desktop Commander config
`set_config_value`	Update a config value

Permission and Security Model

Desktop Commander executes commands with the same permissions as the user running Claude Code. This means:

It can read any file your user account can read (including ~/.ssh, ~/.zshrc, etc.)
It can write to any directory your user account can write to
It can run any command your account can run

Recommendations:

Never give Claude your actual secrets. If it needs an API key for a task, pass it as an environment variable during that specific command, not as a stored file.
Review commands before they run. In Cowork, Claude shows you the command before executing. Read it.
Use get_config and set_config_value to restrict which directories Desktop Commander can access. You can set an allowed-directories whitelist.
Be cautious with kill_process. Killing the wrong PID can terminate system processes.

Setting Up an Allowed-Directories Whitelist

To restrict Desktop Commander to only operate within specific folders:

Use Desktop Commander to set the allowed_directories config to 
["/Users/YOUR_USERNAME/Desktop", "/Users/YOUR_USERNAME/projects"].

Claude calls set_config_value with the allowed_directories list. After this, Desktop Commander will refuse to operate outside those paths.

This is highly recommended for production use.

Common Usage Patterns

Pattern 1: Read a File Before Editing

Read the file at ~/Desktop/my-project/src/index.js and then 
replace the API_BASE_URL value with https://api.newdomain.com

Claude reads the file first (to understand the current content) and then uses edit_block for a targeted replacement.

Pattern 2: Run Tests

In ~/Desktop/my-project, run `npm test` and show me the output.

Claude uses start_process to run the test suite and returns the output. You can follow up with "fix the failing tests" and it will use edit_block to make changes.

Pattern 3: Search Your Codebase

Search ~/Desktop/my-project for all files containing "DEPRECATED" 
and list the file paths and line numbers.

Claude uses start_search (ripgrep) to return matches.

Pattern 4: Git Operations

In ~/Desktop/my-project, run git status, then git add -A, 
then git commit -m "fix: update API base URL", 
but do not git push until I approve.

Claude runs the first three commands and stops before push.

Important rule: Always tell Claude explicitly not to push to GitHub without your approval. Desktop Commander can run git push if you ask it to.

Pattern 5: Create a File Structure

In ~/Desktop/my-project, create the following directory structure:
- src/components/
- src/hooks/
- src/utils/
- src/pages/
And create an empty index.js in each.

Claude uses create_directory and write_file to scaffold the structure.

Troubleshooting

"Tool not found" error in Claude: - Check ~/.claude/mcp_servers.json is valid JSON - Restart Claude Code completely (not just the conversation) - Run npx @desktop-commander/mcp-server --version in terminal to confirm the package exists

Commands fail with "permission denied": - Check if the allowed_directories whitelist is set and excludes the path - Verify your user account has write access to the target path - For system paths, you may need to prefix with sudo -- but confirm you want to do this

Output is truncated: - Desktop Commander truncates very long outputs by default. For large files, use read_file with a byte range, or grep for specific content rather than reading the whole file.

Process starts but no output: - Some processes run in the background and produce no immediate stdout. Use list_processes to see if the process is running, then read_output with the process ID.

Combining with MemPalace

Desktop Commander and MemPalace are designed to work together. A common pattern:

Claude reads MemPalace at session start (loads project context, paths, preferences)
Claude uses Desktop Commander to navigate and edit the actual files
Claude writes session notes back to MemPalace at session end

Set up both (see MemPalace guide) for the most capable local development workflow.

Summary

Desktop Commander takes about 5 minutes to install and transform Claude into an agent that can actually work on your codebase. The key safety practice is the allowed-directories whitelist and the habit of reviewing commands before approving execution. Once configured, it significantly reduces the friction of working with Claude on file-heavy development tasks.

Next: Build an MCP Server in Python with FastMCP