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.
- 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.
- 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
For ChatGPT, Claude web, and other remote clients, see the Remote device launchers. They install Node.js when missing and run Desktop Commander Remote on macOS, Linux, or Windows.
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.
Option 1: Install through npx ⭐ Auto-Updates (Requires Node.js)
Just run this in terminal:
npx @wonderwhy-er/desktop-commander@latest setup
For debugging mode (allows Node.js inspector connection):
npx @wonderwhy-er/desktop-commander@latest setup --debug
Command line options during setup:
--debug: Enable debugging mode for Node.js inspector--no-onboarding: Disable onboarding prompts for new users
Restart Claude if running.
✅ Auto-Updates: Yes - automatically updates when you restart Claude
🔄 Manual Update: Run the setup command again
🗑️ Uninstall: Run npx @wonderwhy-er/desktop-commander@latest remove
Option 2: Using bash script installer (macOS) ⭐ Auto-Updates (Installs Node.js if needed)
curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install.sh | bash
This script handles all dependencies and configuration automatically.
✅ Auto-Updates: Yes
🔄 Manual Update: Re-run the bash installer command above
🗑️ Uninstall: Run npx @wonderwhy-er/desktop-commander@latest remove
Option 3: Installing via Smithery ⭐ Auto-Updates (Requires Node.js)
- Visit: https://smithery.ai/server/@wonderwhy-er/desktop-commander
- Login to Smithery if you haven't already
- Select your client (Claude Desktop) on the right side
- Install with the provided key that appears after selecting your client
- Restart Claude Desktop
✅ Auto-Updates: Yes - automatically updates when you restart Claude
🔄 Manual Update: Visit the Smithery page and reinstall
Option 4: Add to claude_desktop_config manually ⭐ Auto-Updates (Requires Node.js)
Add this entry to your claude_desktop_config.json:
- On Mac:
~/Library/Application Support/Claude/claude_desktop_config.json - On Windows:
%APPDATA%\Claude\claude_desktop_config.json - On Linux:
~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"desktop-commander": {
"command": "npx",
"args": [
"-y",
"@wonderwhy-er/desktop-commander@latest"
]
}
}
}Restart Claude if running.
✅ Auto-Updates: Yes - automatically updates when you restart Claude
🔄 Manual Update: Run the setup command again
🗑️ Uninstall: Run npx @wonderwhy-er/desktop-commander@latest remove or remove the entry from your claude_desktop_config.json
Option 5: Checkout locally ❌ Manual Updates (Requires Node.js)
git clone https://github.com/wonderwhy-er/DesktopCommanderMCP.git
cd DesktopCommanderMCP
npm run setupRestart Claude if running.
The setup command will install dependencies, build the server, and configure Claude's desktop app.
❌ Auto-Updates: No - requires manual git updates
🔄 Manual Update: cd DesktopCommanderMCP && git pull && npm run setup
🗑️ Uninstall: Run npx @wonderwhy-er/desktop-commander@latest remove or remove the cloned directory and MCP server entry from Claude config
Option 6: Docker Installation 🐳 ⭐ Auto-Updates (No Node.js Required)
Perfect for users who want isolation or don't have Node.js installed. Runs in a sandboxed Docker container with a persistent work environment.
Prerequisites: Docker Desktop installed and running, Claude Desktop app installed.
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'))The installer will check Docker, pull the image, prompt for folder mounting, and configure Claude Desktop.
Docker persistence: Your tools, configs, work files, and package caches all survive restarts.
Manual Docker Configuration
Basic setup (no file access):
{
"mcpServers": {
"desktop-commander-in-docker": {
"command": "docker",
"args": ["run", "-i", "--rm", "mcp/desktop-commander:latest"]
}
}
}With folder mounting:
{
"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"
]
}
}
}Advanced folder mounting:
{
"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"
]
}
}
}Docker Management Commands
macOS/Linux:
# 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) --resetWindows PowerShell:
# 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")) -HelpTroubleshooting: Reset and reinstall from scratch:
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)✅ Auto-Updates: Yes - latest tag automatically gets newer versions
🔄 Manual Update: docker pull mcp/desktop-commander:latest then restart Claude
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:
Cursor
Or add manually to ~/.cursor/mcp.json (global) or .cursor/mcp.json in your project folder (project-specific).
See Cursor MCP docs for more info.
Windsurf
Add to ~/.codeium/windsurf/mcp_config.json. See Windsurf MCP docs for more info.
VS Code / GitHub Copilot
Add to .vscode/mcp.json in your project or VS Code User Settings (JSON). Make sure MCP is enabled under Chat > MCP. Works in Agent mode.
See VS Code MCP docs for more info.
Cline
Configure through the Cline extension settings in VS Code. Open the Cline sidebar, click the MCP Servers icon, and add the JSON configuration above. See Cline MCP docs for more info.
Roo Code
Add to your Roo Code MCP configuration file. See Roo Code MCP docs for more info.
Claude Code
claude mcp add --scope user desktop-commander -- npx -y @wonderwhy-er/desktop-commander@latestRemove --scope user to install for the current project only. See Claude Code MCP docs for more info.
Trae
Use the "Add manually" feature and paste the JSON configuration above. See Trae MCP docs for more info.
Kiro
Navigate to Kiro > MCP Servers, click + Add, and paste the JSON configuration above. See Kiro MCP docs for more info.
Codex (OpenAI)
Codex uses TOML configuration. Run this command to add Desktop Commander:
codex mcp add desktop-commander -- npx -y @wonderwhy-er/desktop-commander@latestOr manually add to ~/.codex/config.toml:
[mcp_servers.desktop-commander]
command = "npx"
args = ["-y", "@wonderwhy-er/desktop-commander@latest"]See Codex MCP docs for more info.
JetBrains (AI Assistant)
In JetBrains IDEs, go to Settings → Tools → AI Assistant → Model Context Protocol (MCP), click + Add, select As JSON, and paste the JSON configuration above. See JetBrains MCP docs for more info.
Gemini CLI
Add to ~/.gemini/settings.json:
{
"mcpServers": {
"desktop-commander": {
"command": "npx",
"args": ["-y", "@wonderwhy-er/desktop-commander@latest"]
}
}
}See Gemini CLI docs for more info.
Augment Code
Press Cmd/Ctrl+Shift+P, open the Augment panel, and add a new MCP server named desktop-commander with the JSON configuration above. See Augment Code MCP docs for more info.
Qwen Code
Run this command to add Desktop Commander:
qwen mcp add desktop-commander -- npx -y @wonderwhy-er/desktop-commander@latestOr add to .qwen/settings.json (project) or ~/.qwen/settings.json (global). See Qwen Code MCP docs for more info.
ChatGPT / Claude Web (Remote MCP)
Use Desktop Commander from ChatGPT, Claude web, and other AI services while commands still execute on your computer.
Start the Remote Device:
npx @wonderwhy-er/desktop-commander@latest remoteOn first run, complete browser authentication, then connect your AI at mcp.desktopcommander.app.
- Stop the local device temporarily with
Ctrl+C - See available CLI options with
npx @wonderwhy-er/desktop-commander@latest remote --help - See Remote MCP setup, logout/revocation, CLI reference, and troubleshooting
- ✅ The Remote Device only accepts commands while it is running
- ✅ Commands execute locally under your user permissions
- ✅ Secure OAuth authentication and encrypted communication channel
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.
- Option 5 (local checkout):
cd DesktopCommanderMCP && git pull && npm run setup
The easiest way to completely remove Desktop Commander:
npx @wonderwhy-er/desktop-commander@latest removeThis 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
If the automatic uninstaller doesn't work or you prefer manual removal:
- 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
- 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.
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
Once Desktop Commander is installed and Claude Desktop is restarted, you're ready to supercharge your Claude experience!
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
The server provides a comprehensive set of tools organized into several categories: