DesktopCommanderMCP is a server based on the Model Context Protocol (MCP), designed specifically to provide AI clients such as Claude with terminal control, filesystem search, and file editing capabilities, allowing AI to search, update, and manage files and run terminal commands within the chat interface. It is built on top of the MCP Filesystem Server, additionally providing advanced features such as search-and-replace editing, process management, and dataset analysis.
Purpose and positioning: Integrate various development tools into a single chat interface, enabling AI to execute long-running terminal commands, manage processes, and directly read, write, search, and edit code and text files. Users can use the host client's subscription instead of being billed by API tokens.
Main capabilities:
- Terminal commands: Execute terminal commands with streaming output, support command timeouts and background execution, and provide interactive process control.
- Process management: List and terminate processes, support session management to handle long-running commands, and paginate process output (controlled via offset/length) to prevent context overflow.
- Filesystem operations: Read/write text, Excel (.xlsx, .xls), PDF, and DOCX files; create/list directories; recursive directory listing (configurable depth and protection against context overflow); move files/directories; search files and content (including Excel content); get file metadata; support negative offsets to read from the end of a file (similar to Unix tail).
- Code editing: Use precise text replacement for small changes, support full file rewriting for large changes, support multi-file, pattern-based replacement, and recursive code or text search based on vscode-ripgrep.
- In-memory execution: Run Python, Node.js, and R code without saving files.
- Instant data analysis: Analyze CSV, JSON, and Excel files.
- Native file format support: Excel (read/write/edit/search), PDF (text extraction, creation from Markdown, modification of existing PDFs), DOCX (read, create, edit, search, with XML editing and Markdown-to-DOCX support).
- Remote AI control: Use Desktop Commander from AI services such as ChatGPT and Claude web via Remote MCP.
- File preview UI: Provide visual file previews in Claude Desktop, supporting rendering Markdown, inline images, expandable content, a built-in Markdown editor, and quick access via "Open in Folder".
- Local tool call history and audit logs: Tool calls and parameters are recorded locally, and recent call history can be viewed via get_recent_tool_calls (with limited output previews), with size-based rotation/pruning keeping history files bounded.
- Configuration management: Get/set configuration values, batch update multiple settings, and dynamically change configuration without restarting the server.
- Security guardrails (not a sandbox, see SECURITY.md for details): symlink traversal protection in file operations, a command blacklist to prevent accidental execution, and Docker isolation for complete isolation.
Installation and usage: Multiple installation methods are supported:
- Run npx @wonderwhy-er/desktop-commander@latest setup in the terminal (supports --debug debug mode and --no-onboarding to disable new user onboarding).
- bash installation script.
- Smithery (https://smithery.ai/server/@wonderwhy-er/desktop-commander）。
- Manually edit claude_desktop_config.json (Mac: ~/Library/Application Support/Claude/claude_desktop_config.json; Windows: %APPDATA%\Claude\claude_desktop_config.json; Linux: ~/.config/Claude/claude_desktop_config.json).
- Clone the repository locally: cd DesktopCommanderMCP && git pull && npm run setup.
- Run isolated with Docker (requires Docker Desktop, persistent working environment).
Other MCP-compatible clients are also supported: Cursor (~/.cursor/mcp.json or the project's .cursor/mcp.json), Windsurf (~/.codeium/windsurf/mcp_config.json), VS Code (.vscode/mcp.json or user settings), Cline, Roo Code, Claude Code, Trae, Kiro, Codex (~/.codex/config.toml), JetBrains IDEs, Gemini CLI (~/.gemini/settings.json), Augment Code, Qwen Code (.qwen/settings.json or ~/.qwen/settings.json), etc.
Remote device: start it with npx @wonderwhy-er/desktop-commander@latest remote; the first run requires browser authentication, then connect the AI at mcp.desktopcommander.app. The remote device only accepts commands while running, and commands are executed locally under the user's permissions, using secure OAuth authentication and an encrypted channel.
Update and uninstall: options 1, 2, 3, 4, and 6 support automatic updates (automatically updated when Claude restarts); option 5 (local checkout) requires manual updates (git pull && npm run setup). To uninstall, run npx @wonderwhy-er/desktop-commander@latest remove, or manually remove the desktop-commander entry from mcpServers in claude_desktop_config.json.
Tool example: the edit_block tool supports fuzzy-search fallback, character-level diff display ({-removed-}{+added+} format), replacing multiple matches via the expected_replacements parameter, and comprehensive logging.
Use cases: Suitable for developers and advanced users who need the AI to directly execute terminal commands locally, manage processes, search and edit code/text files, and analyze data. It can also be used for testing, development, or scenarios that need to run in a fully isolated environment (Docker).
Limitations and caveats:
- It positions itself as a safety guardrail rather than a sandbox; full isolation requires Docker.
- The remote device only accepts commands while running, and commands are executed locally with the user's permissions.
- Different installation methods have different update behaviors.
- Other features, fees, prices, platforms, or effects not mentioned in the materials are not provided for now.
