Desktop Commander MCP Server

MCP server that gives AI agents terminal control, file system search, and surgical file editing capabilities on your local machine.

Developer Tools by wonderwhy-er (Eduard Ruzga) None active

GitHub Docs npm: @wonderwhy-er/desktop-commander

Overview

Desktop Commander is an open-source MCP server that extends AI assistants like Claude with the ability to interact with your computer's filesystem and terminal. It enables searching, updating, and managing files and running shell commands, turning the AI into a general-purpose development and automation assistant that works outside the constraints of a typical AI code editor.

The server covers file operations (text, Excel, PDF, and DOCX), recursive directory listings, pattern-based file and content search, and surgical text replacements via diff-style edits. On the process side, it can start long-running processes, stream their output, interact with them (including REPLs, SSH, and database sessions), and terminate them by PID. It also supports in-memory code execution for Python, Node.js, and R, which is useful for ad-hoc data analysis on CSV, JSON, and Excel files.

Desktop Commander is notable for working with Claude Desktop subscriptions (no API token cost), supporting many MCP clients (Claude Desktop, Cursor, Windsurf, VS Code, Cline, Claude Code, Gemini CLI, and others), and offering a Docker installation for host isolation. It is community-maintained by wonderwhy-er and ships an optional companion desktop app with visual file previews and additional features.

Tools

Tool	Description
`get_config`	Returns the full Desktop Commander configuration as JSON.
`set_config_value`	Updates a runtime configuration value such as defaultShell, allowedDirectories, or fileWriteLineLimit.
`start_process`	Starts a shell process or program with smart readiness detection.
`interact_with_process`	Sends input to a running interactive process (REPLs, SSH, DB shells).
`read_process_output`	Streams output from a running process with pagination.
`force_terminate`	Stops an active terminal session by its session ID.
`list_sessions`	Lists all active terminal sessions.
`list_processes`	Lists running OS processes with metadata.
`kill_process`	Terminates a process by PID.
`read_file`	Reads text, Excel, or PDF files with line-based pagination, including negative offsets for tail reads. Supports URLs.
`read_multiple_files`	Reads multiple files in a single batch call.
`write_file`	Creates or appends to text or Excel files. Use write_pdf for PDFs.
`write_pdf`	Creates or modifies PDFs from markdown with HTML/CSS support.
`create_directory`	Creates a directory if it does not already exist.
`list_directory`	Lists directory contents recursively with configurable depth.
`move_file`	Renames or moves a file or directory.
`start_search`	Starts a streaming search across files and contents.
`get_more_search_results`	Retrieves paginated results from an active search.
`stop_search`	Halts an active search.
`list_searches`	Lists currently active search sessions.
`get_file_info`	Returns detailed metadata for a file, including Excel sheet info.
`edit_block`	Applies surgical search-and-replace edits with fuzzy fallback. Supports Excel cell ranges.
`get_usage_stats`	Returns personal Desktop Commander usage metrics.
`get_recent_tool_calls`	Returns recent tool call history with arguments for debugging.
`give_feedback_to_desktop_commander`	Opens the Desktop Commander feedback form.

Setup Guide

Prerequisites

Claude Desktop (or another MCP-compatible client)
Node.js v14 or newer for the npx-based methods
Docker Desktop if you choose the Docker installation

Option 1: One-line setup (recommended)

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

Restart Claude Desktop after the command completes.

Option 2: Manual config

Edit your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Add the server entry:

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

Option 3: Docker (host isolation)

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'))

Hardening

After install, use set_config_value to set allowedDirectories, blockedCommands, and defaultShell to match your security requirements. Note that directory allowlists apply to filesystem tools only, not to terminal commands. For strict isolation, prefer the Docker installation.

Uninstall

npx @wonderwhy-er/desktop-commander@latest remove

Use Cases

Explore an unfamiliar codebase by recursively listing directories, searching for symbols across files, and reading source with pagination
Run and supervise long-running dev tasks (builds, test suites, dev servers) with start_process, read_process_output, and force_terminate
Apply surgical edits across many files using edit_block instead of full rewrites, keeping diffs small and token usage low
Perform ad-hoc data analysis on local CSV, JSON, or Excel files using in-memory Python/Node.js/R execution
Generate or modify PDF reports from markdown and edit Excel/DOCX files directly from chat

Example Prompts

"Search my ~/projects/api folder for any usage of legacyAuthToken and show me the surrounding lines."
"Run npm test in ~/work/frontend, stream the output, and stop it if more than 5 tests fail."
"Open report.xlsx, change cell B12 to 2026, and save it."
"Read the last 200 lines of /var/log/nginx/error.log and summarize the recurring errors."
"Refactor every occurrence of getUserById to fetchUser across the src/ directory using surgical edits."

Pros

Broad capability set covering filesystem, terminal, process control, and document editing in one server
Works with many MCP clients including Claude Desktop, Cursor, Windsurf, VS Code, Cline, Claude Code, and Gemini CLI
Surgical edit_block diffs and pagination help control token usage on large files
Docker installation option provides host isolation for stricter security setups

Limitations

Powerful by design: terminal access bypasses directory allowlists, so misuse or prompt injection can damage the host system
Command blocklists and allowed directories can be circumvented via symlinks, command substitution, or code execution
Community-maintained rather than backed by a vendor, so support and SLAs depend on the maintainer

Alternatives

Filesystem MCP server (modelcontextprotocol/servers): official, narrower filesystem-only scope
Shell/Terminal MCP servers: various community shell command servers without the file editing extras
Built-in tools in Cursor or Claude Code for file editing and command execution when you do not want a separate MCP server