Desktop Commander MCP

What is Desktop Commander MCP?

Desktop Commander MCP is a Model Context Protocol (MCP) server that enables advanced system-level interaction between AI language models (like Claude Desktop) and your local machine. It goes far beyond typical AI editors by wrapping essential developer tools—terminal commands, file management, code editing, and automation—behind a secure interface that works directly through Claude Desktop, without requiring per-token API credits. It is designed to turn Claude into a versatile developer assistant capable of full-codebase exploration, precise changes, automation scripting, and workflow management across your entire OS, not just inside an IDE.

How to Configure Desktop Commander MCP

Install Claude Desktop: Download and install Claude Desktop.
Quick Installation via npx: Run npx @wonderwhy-er/desktop-commander@latest setup in your terminal.
Other Installation Options:
- Use the Smithery CLI with npx -y @smithery/cli install @wonderwhy-er/desktop-commander --client claude
- Use the bash script for macOS: curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install.sh | bash
- Edit your claude_desktop_config.json, adding the server config under mcpServers
- Or clone/build locally with git clone ..., npm run setup.
Restart Claude Desktop after setup to enable the new MCP server.
Configure Settings:
- Use get_config({}) and set_config_value({ key, value }) tools within Claude chat to adjust options like blocked commands, allowedDirectories, or default shell.
- Always verify configuration changes with get_config({}).
- For security, maintain a dedicated configuration chat and specify exact directory access limits.

Settings are persisted in config.json within the server's working directory. You can disable telemetry directly by asking Claude to "disable telemetry" in chat.

How to Use Desktop Commander MCP

Start Claude Desktop and open a new chat.
Interact Using Natural Language: Ask Claude to perform operations such as reading, searching, editing files, running terminal commands, or managing processes—Claude will invoke the corresponding MCP tools.

Manual Tool Calls: You may use the MCP tool function names directly, for example:

execute_command({ "command": "ls -la", "shell": "/bin/zsh" })
read_file({ "path": "README.md" })
edit_block({ "changes": "...edit block format..." })

Handling Long-running Tasks:
- For processes that continue in the background, use list_sessions to monitor, read_output to fetch command output, and force_terminate to stop them.
Text/Code Search and Edit:
- Use edit block syntax for precise replacements.
- Use tools like search_code, search_files, and edit_block to perform and coordinate sophisticated codebase changes.
Switching Shells:
- Select your preferred shell via the shell argument in command tools—e.g., bash, zsh, or powershell.

The interface lets you seamlessly automate tasks, perform system scripting, manage files and processes, and edit code—all via conversations with Claude.

Key Features

Terminal Command Execution: Run commands with live output, timeouts, and custom shells.
Background Process Management: List, monitor, and kill running processes or terminal sessions.
Configuration Management: Get/set server settings, including command restrictions and directory access with no restart needed.
File System Operations: Read, write, move, search, and get info for files/directories; supports batch operations and pattern searches.
Archival Search/Editing: Fuzzy, multi-occurrence text/code search and pattern replacements using secure edit block formats.
Advanced Code Editing: Surgical text changes, multi-file support, pattern matching, and integration with ripgrep for deep codebase exploration.
Image and URL Handling: read_file can preview and analyze both local files and remote web resources, supporting both text and images.
Security Controls: Define allowed directories, block risky commands, and review telemetry (opt-out supported).
Cross-Platform: Fully works on macOS, Windows, and Linux, with automatic environment-specific fixes.

Use Cases

Exploring, searching, and understanding large or complex codebases in minutes
Precise, surgical refactoring or patching of code across multiple files/projects
Generating documentation or diagrams by extracting and processing code/text
Automating repetitive or cross-project developer tasks from a single chat interface
Performing system scripting, environment setup, and process management via AI
Quickly debugging, trial-executing, or terminating processes, builds, and server runs
Working across multiple OS environments without per-token API cost

FAQ

1. What is Desktop Commander MCP? It's an MCP server that empowers Claude Desktop to fully interact with your file system and OS, enabling tasks like codebase exploration, fine-grained code editing, automation, and terminal/process control through natural language.

2. How does this differ from tools like Cursor or Windsurf? Desktop Commander MCP offers broad OS-level control beyond any IDE, supports multi-project and multi-directory workflows, provides full-file access (not chunks), and leverages the Claude Desktop Pro plan without additional per-token API costs.

3. Does Desktop Commander require API credits or extra payment? No—once you have Claude Desktop Pro, all operations happen locally with no extra usage or per-token charges.

4. How do I update Desktop Commander? If installed via npx or Smithery, Desktop Commander updates automatically when you restart Claude Desktop. For manual installs, just re-run the setup command.

5. Is telemetry data collected? Telemetry is minimal and non-personal by default. You can opt out at any time by asking Claude: "disable telemetry".

Tool Name	Description
get_config	Retrieves the current server configuration (blocked commands, default shell, allowed directories) as JSON.
set_config_value	Updates a specific configuration value such as allowed directories, blocked commands, or default shell.
execute_command	Executes a terminal command with options for timeout and shell selection, streams command output.
read_output	Fetches new output from a currently running terminal command/session.
force_terminate	Forcefully terminates a running terminal session or command by session id.
list_sessions	Lists all running or backgrounded terminal command sessions.
list_processes	Shows all running OS processes with detailed info (PID, command, etc.).
kill_process	Terminates a process by its process ID (PID).
read_file	Reads and returns content from a local file or URL; supports both text and image data.
read_multiple_files	Reads the contents of multiple files at once (batch operation).
write_file	Rewrites an entire file with new content (suitable for large changes).
create_directory	Creates a new directory or ensures it exists.
list_directory	Provides a detailed listing of files and subdirectories at a given path.
move_file	Moves or renames files or directories.
search_files	Finds files by name with case-insensitive substring matching and fuzzy search.
search_code	Searches within file contents for text/code patterns (ripgrep powered) recursively.
get_file_info	Retrieves detailed metadata about a file or directory (e.g., size, timestamps, type).
edit_block	Performs precise, pattern-based text/code replacement using an edit block format for surgical changes.