桌面命令MCP服务器

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.

<details> <summary><b>Option 1: Install through npx ⭐ Auto-Updates (Requires Node.js)</b></summary>

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

</details>

<details> <summary><b>Option 2: Using bash script installer (macOS) ⭐ Auto-Updates (Installs Node.js if needed)</b></summary>

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

✅ Auto-Updates: Yes 🔄 Manual Update: Re-run the bash installer command above 🗑️ Uninstall: Run npx @wonderwhy-er/desktop-commander@latest remove

</details>

<details> <summary><b>Option 3: Installing via Smithery ⭐ Auto-Updates (Requires Node.js)</b></summary>

1. Visit: https://smithery.ai/server/@wonderwhy-er/desktop-commander
2. Login to Smithery if you haven't already
3. Select your client (Claude Desktop) on the right side
4. Install with the provided key that appears after selecting your client
5. Restart Claude Desktop

✅ Auto-Updates: Yes - automatically updates when you restart Claude 🔄 Manual Update: Visit the Smithery page and reinstall

</details>

<details> <summary><b>Option 4: Add to claude_desktop_config manually ⭐ Auto-Updates (Requires Node.js)</b></summary>

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"
      ]
    }
  }
}

✅ 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

</details>

<details> <summary><b>Option 5: Checkout locally ❌ Manual Updates (Requires Node.js)</b></summary>

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

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

</details>

<details> <summary><b>Option 6: Docker Installation 🐳 ⭐ Auto-Updates (No Node.js Required)</b></summary>

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.

<details> <summary>Manual Docker Configuration</summary>

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"
      ]
    }
  }
}

</details>

<details> <summary>Docker Management Commands</summary>

macOS/Linux: ```bash

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:

<details> <summary><b>Cursor</b></summary><br>

View MCP Server in Directory

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.

</details>

<details> <summary><b>Windsurf</b></summary>

Add to ~/.codeium/windsurf/mcp_config.json. See Windsurf MCP docs for more info.

</details>

<details> <summary><b>VS Code / GitHub Copilot</b></summary>

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.

</details>

<details> <summary><b>Cline</b></summary>

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.

</details>

<details> <summary><b>Roo Code</b></summary>

Add to your Roo Code MCP configuration file. See Roo Code MCP docs for more info.

</details>

<details> <summary><b>Claude Code</b></summary>

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

Remove --scope user to install for the current project only. See Claude Code MCP docs for more info.

</details>

<details> <summary><b>Trae</b></summary>

Use the "Add manually" feature and paste the JSON configuration above. See Trae MCP docs for more info.

</details>

<details> <summary><b>Kiro</b></summary>

Navigate to Kiro > MCP Servers, click + Add, and paste the JSON configuration above. See Kiro MCP docs for more info.

</details>

<details> <summary><b>Codex (OpenAI)</b></summary>

Codex uses TOML configuration. Run this command to add Desktop Commander:

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

Or 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.

</details>

<details> <summary><b>JetBrains (AI Assistant)</b></summary>

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.

</details>

<details> <summary><b>Gemini CLI</b></summary>

Add to ~/.gemini/settings.json:

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

See Gemini CLI docs for more info.

</details>

<details> <summary><b>Augment Code</b></summary>

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.

</details>

<details> <summary><b>Qwen Code</b></summary>

Run this command to add Desktop Commander:

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

Or add to .qwen/settings.json (project) or ~/.qwen/settings.json (global). See Qwen Code MCP docs for more info.

</details>

<details> <summary><b>ChatGPT / Claude Web (Remote MCP)</b></summary>

Use Desktop Commander from ChatGPT, Claude web, and other AI services via Remote MCP — no desktop app required.

👉 Get started at mcp.desktopcommander.app

How it works: 1. You run a lightweight Remote Device on your computer 2. It connects securely to the cloud Remote MCP service 3. Your AI sends commands through the cloud to your device 4. Commands execute locally, results return to your AI 5. You stay in control — stop anytime with Ctrl+C

Updating & Uninstalling Desktop Commander

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!

Docker Support

Installation Instructions

1. Install Docker for Windows/Mac - Download and install Docker Desktop from docker.com

2. Get Desktop Commander Docker Configuration - Visit: https://hub.docker.com/mcp/server/desktop-commander/manual - Option A: Use the provided terminal command for automated setup - Option B: Click "Standalone" to get the config JSON and add it manually to your Claude Desktop config

3. Mount Your Machine Folders (Coming Soon) - Instructions on how to mount your local directories into the Docker container will be provided soon - This will allow you to work with your files while maintaining complete isolation

Benefits of Docker Usage

• Complete isolation from your host system
• Consistent environment across different machines
• Easy cleanup - just remove the container when done
• Perfect for testing new features or configurations

For npx installations, modify your claude_desktop_config.json:

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

When onboarding is automatically disabled: - When the MCP client name is set to "desktop-commander" - When using the --no-onboarding flag - After users have used onboarding prompts or made 10+ tool calls

Debug information: The server will log when onboarding is disabled: "Onboarding disabled via --no-onboarding flag"

Or if installed locally

npm run setup:debug ```

This will: 1. Configure Claude to use a separate "desktop-commander" server 2. Enable Node.js inspector protocol with --inspect-brk=9229 flag 3. Pause execution at the start until a debugger connects 4. Enable additional debugging environment variables

To connect a debugger: - In Chrome, visit chrome://inspect and look for the Node.js instance - In VS Code, use the "Attach to Node Process" debug configuration - Other IDEs/tools may have similar "attach" options for Node.js debugging

Important debugging notes: - The server will pause on startup until a debugger connects (due to the --inspect-brk flag) - If you don't see activity during debugging, ensure you're connected to the correct Node.js process - Multiple Node processes may be running; connect to the one on port 9229 - The debug server is identified as "desktop-commander-debug" in Claude's MCP server list

Troubleshooting: - If Claude times out while trying to use the debug server, your debugger might not be properly connected - When properly connected, the process will continue execution after hitting the first breakpoint - You can add additional breakpoints in your IDE once connected

I'm having trouble installing or using the tool. Where can I get help?

Join our Discord server for community support, check the GitHub issues for known problems, or review the full FAQ for troubleshooting tips. You can also visit our website FAQ section for a more user-friendly experience. If you encounter a new issue, please consider opening a GitHub issue with details about your problem.

Usage

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

Quick Examples

Data Analysis:

"Analyze sales.csv and show top customers" → Claude runs Python code in memory

Remote Access:

"SSH to my server and check disk space" → Claude maintains SSH session

Development:

"Start Node.js and test this API" → Claude runs interactive Node session

Tool Usage Examples

Search/Replace Block Format: ``` filepath.ext <<<<<<< SEARCH

🐳 Isolated Environment Usage

Desktop Commander can be run in Docker containers for complete isolation from your host system, providing zero risk to your computer. This is perfect for testing, development, or when you want complete sandboxing.

What are the most common use cases?

• Exploring and understanding complex codebases
• Generating diagrams and documentation
• Automating tasks across your system
• Working with multiple projects simultaneously
• Making surgical code changes with precise control

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

Configuration Management

Configuration Tools

You can manage server configuration using the provided tools:

// Get the entire config
get_config({})

// Set a specific config value
set_config_value({ "key": "defaultShell", "value": "/bin/zsh" })

// Set multiple config values using separate calls
set_config_value({ "key": "defaultShell", "value": "/bin/bash" })
set_config_value({ "key": "allowedDirectories", "value": ["/Users/username/projects"] })

The configuration is saved to config.json in the server's working directory and persists between server restarts.

Understanding fileWriteLineLimit

The fileWriteLineLimit setting controls how many lines can be written in a single write_file operation (default: 50 lines). This limit exists for several important reasons:

Why the limit exists: - AIs are wasteful with tokens: Instead of doing two small edits in a file, AIs may decide to rewrite the whole thing. We're trying to force AIs to do things in smaller changes as it saves time and tokens - Claude UX message limits: There are limits within one message and hitting "Continue" does not really work. What we're trying here is to make AI work in smaller chunks so when you hit that limit, multiple chunks have succeeded and that work is not lost - it just needs to restart from the last chunk

Setting the limit:

// You can set it to thousands if you want
set_config_value({ "key": "fileWriteLineLimit", "value": 1000 })

// Or keep it smaller to force more efficient behavior
set_config_value({ "key": "fileWriteLineLimit", "value": 25 })

Maximum value: You can set it to thousands if you want - there's no technical restriction.

Best practices: - Keep the default (50) to encourage efficient AI behavior and avoid token waste - The system automatically suggests chunking when limits are exceeded - Smaller chunks mean less work lost when Claude hits message limits

Command Line Options

Desktop Commander supports several command line options for customizing behavior:

Do I need to pay for API credits?

No. This tool works with Claude Desktop's standard Pro subscription ($20/month), not with API calls, so you won't incur additional costs beyond the subscription fee.

Model Context Protocol Integration

This project extends the MCP Filesystem Server to enable: - Local server support in Claude Desktop - Full system command execution - Process management - File operations - Code editing with search/replace blocks

Created as part of exploring Claude MCPs: https://youtube.com/live/TlbjFDbl5Us

Frequently Asked Questions

Here are answers to some common questions. For a more comprehensive FAQ, see our detailed FAQ document.