Desktop Commander MCP

Search, update, manage files and run terminal commands with AI

Work with code and text, run processes, and automate tasks, going far beyond other AI editors - while using host client subscriptions instead of API token costs.

🖥️ Try the Desktop Commander App (Beta)

Want a better experience? The Desktop Commander App gives you everything the MCP server does, plus:

• Use any AI model — Claude, GPT-4.5, Gemini 2.5, or any model you prefer
• See file changes live — visual file previews as AI edits your files
• Add custom MCPs and context — extend with your own tools, no config files
• Coming soon — skills system, dictation, background scheduled tasks, and more

👉 Download the App (macOS & Windows)

The MCP server below still works great with Claude Desktop and other MCP clients — the app is for those who want a dedicated, polished experience.

Table of Contents

• Features
• How to install
• Getting Started
• Usage
• File Preview UI & Markdown Editor
• Handling Long-Running Commands
• Work in Progress and TODOs
• Sponsors and Supporters
• Website
• Media
• Testimonials
• Frequently Asked Questions
• Contributing
• License

All of your AI development tools in one place. Desktop Commander puts all dev tools in one chat. Execute long-running terminal commands on your computer and manage processes through Model Context Protocol (MCP). Built on top of MCP Filesystem Server to provide additional search and replace file editing capabilities.

Features

• Remote AI Control - Use Desktop Commander from ChatGPT, Claude web, and other AI services via Remote MCP
• File Preview UI - Visual file previews in Claude Desktop with rendered markdown, inline images, expandable content, built-in markdown editor, and quick "Open in folder" access
• Enhanced terminal commands with interactive process control
• Execute code in memory (Python, Node.js, R) without saving files
• Instant data analysis - just ask to analyze CSV/JSON/Excel files
• Native Excel file support - Read, write, edit, and search Excel files (.xlsx, .xls, .xlsm) without external tools
• PDF support - Read PDFs with text extraction, create new PDFs from markdown, modify existing PDFs
• DOCX support - Read, create, edit, and search Word documents (.docx) with surgical XML editing and markdown-to-DOCX conversion
• Interact with running processes (SSH, databases, development servers)
• Execute terminal commands with output streaming
• Command timeout and background execution support
• Process management (list and kill processes)
• Session management for long-running commands
• Process output pagination - Read terminal output with offset/length controls to prevent context overflow
• Server configuration management:
  • Get/set configuration values
  • Update multiple settings at once
  • Dynamic configuration changes without server restart
• Full filesystem operations:
  • Read/write files (text, Excel, PDF, DOCX)
  • Create/list directories
  • Recursive directory listing with configurable depth and context overflow protection for large folders
  • Move files/directories
  • Search files and content (including Excel content)
  • Get file metadata
  • Negative offset file reading: Read from end of files using negative offset values (like Unix tail)
• Code editing capabilities:
  • Surgical text replacements for small changes
  • Full file rewrites for major changes
  • Multiple file support
  • Pattern-based replacements
  • vscode-ripgrep based recursive code or text search in folders
• Local tool-call history and audit logs:
  • Tool calls and arguments are recorded locally on the machine running Desktop Commander
  • Recent call history with bounded output previews is available through get_recent_tool_calls
  • Size-based rotation/trimming keeps the active history files bounded
• Safety guardrails (not a sandbox — see SECURITY.md):
  • Symlink traversal prevention on file operations
  • Command blocklist for accidental execution
  • Docker isolation for complete isolation

How to install

Install in Claude Desktop

Desktop Commander offers multiple installation methods for Claude Desktop.

📋 Update & Uninstall Information: Options 1, 2, 3, 4, and 6 have automatic updates. Option 5 requires manual updates. See below for details.

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

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

curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install.sh | bash

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

git clone https://github.com/wonderwhy-er/DesktopCommanderMCP.git
cd DesktopCommanderMCP
npm run setup

bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh)

iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.ps1'))

{
  "mcpServers": {
    "desktop-commander-in-docker": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "mcp/desktop-commander:latest"]
    }
  }
}

{
  "mcpServers": {
    "desktop-commander-in-docker": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/username/Desktop:/mnt/desktop",
        "-v", "/Users/username/Documents:/mnt/documents",
        "mcp/desktop-commander:latest"
      ]
    }
  }
}

{
  "mcpServers": {
    "desktop-commander-in-docker": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "dc-system:/usr",
        "-v", "dc-home:/root", 
        "-v", "dc-workspace:/workspace",
        "-v", "dc-packages:/var",
        "-v", "/Users/username/Projects:/mnt/Projects",
        "-v", "/Users/username/Downloads:/mnt/Downloads",
        "mcp/desktop-commander:latest"
      ]
    }
  }
}

# Check status
bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh) --status

# Reset all persistent data
bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh) --reset

# Check status
$script = (New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.ps1'); & ([ScriptBlock]::Create("$script")) -Status

# Reset all data
$script = (New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.ps1'); & ([ScriptBlock]::Create("$script")) -Reset

# Show help
$script = (New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.ps1'); & ([ScriptBlock]::Create("$script")) -Help

bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh) --reset && bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh)

Install in Other Clients

Desktop Commander works with any MCP-compatible client. The standard JSON configuration is:

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

Add this to your client's MCP configuration file at the locations below:

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

codex mcp add desktop-commander -- npx -y @wonderwhy-er/desktop-commander@latest

[mcp_servers.desktop-commander]
command = "npx"
args = ["-y", "@wonderwhy-er/desktop-commander@latest"]

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

qwen mcp add desktop-commander -- npx -y @wonderwhy-er/desktop-commander@latest

Updating & Uninstalling Desktop Commander

Automatic Updates (Options 1, 2, 3, 4 & 6)

Options 1 (npx), Option 2 (bash installer), 3 (Smithery), 4 (manual config), and 6 (Docker) automatically update to the latest version whenever you restart Claude. No manual intervention needed.

Manual Updates (Option 5)

• Option 5 (local checkout): cd DesktopCommanderMCP && git pull && npm run setup

Uninstalling Desktop Commander

🤖 Automatic Uninstallation (Recommended)

The easiest way to completely remove Desktop Commander:

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

This automatic uninstaller will:

• ✅ Remove Desktop Commander from Claude's MCP server configuration
• ✅ Create a backup of your Claude config before making changes
• ✅ Provide guidance for complete package removal
• ✅ Restore from backup if anything goes wrong

🔧 Manual Uninstallation

If the automatic uninstaller doesn't work or you prefer manual removal:

Remove from Claude Configuration

1. Locate 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

2. Edit the config file:

• Open the file in a text editor
• Find and remove the "desktop-commander" entry from the "mcpServers" section
• Save the file

Example - Remove this section:

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

Close and restart Claude Desktop to complete the removal.

🆘 Troubleshooting

If automatic uninstallation fails:

• Use manual uninstallation as a fallback

If Claude won't start after uninstalling:

• Restore the backup config file created by the uninstaller
• Or manually fix the JSON syntax in your claude_desktop_config.json

Need help?

• Join our Discord community: https://discord.com/invite/kQ27sNnZr7

Getting Started

Once Desktop Commander is installed and Claude Desktop is restarted, you're ready to supercharge your Claude experience!

🚀 New User Onboarding

Desktop Commander includes intelligent onboarding to help you discover what's possible:

For New Users: When you're just getting started (fewer than 10 successful commands), Claude will automatically offer helpful getting-started guidance and practical tutorials after you use Desktop Commander successfully.

Request Help Anytime: You can ask for onboarding assistance at any time by simply saying:

• "Help me get started with Desktop Commander"
• "Show me Desktop Commander examples"
• "What can I do with Desktop Commander?"

Claude will then show you beginner-friendly tutorials and examples, including:

• 📁 Organizing your Downloads folder automatically
• 📊 Analyzing CSV/Excel files with Python
• ⚙️ Setting up GitHub Actions CI/CD
• 🔍 Exploring and understanding codebases
• 🤖 Running interactive development environments

Usage

The server provides a comprehensive set of tools organized into several categories:

Available Tools