Manual Installation

Step-by-step manual configuration for advanced users who want complete control

Manual Installation

For advanced users who want complete control over the installation process, this guide provides step-by-step manual configuration of Desktop Commander.

When to Use Manual Installation

Full Control

Complete control over every aspect of the installation and configuration

Custom Setups

Non-standard installations, custom paths, or specialized environments

Troubleshooting

Diagnose and fix issues with automatic installation methods

Learning

Understand exactly how Desktop Commander integrates with Claude Desktop

Prerequisites

Before starting manual installation:

• Claude Desktop installed and configured
• Claude Pro or Max subscription
• Node.js v18.18.0+ installed and working
• Text editor for editing JSON configuration files
• Terminal/Command Prompt access

Step 1: Locate Claude Desktop Configuration

Find your Claude Desktop configuration file:

Windows

Standard Path: %APPDATA%\Claude\claude_desktop_config.json

Full Path: C:\Users\[YourUsername]\AppData\Roaming\Claude\claude_desktop_config.json

How to access:

1. Press Win + R
2. Type %APPDATA%\Claude and press Enter
3. Look for claude_desktop_config.json

If file doesn’t exist: Run Claude Desktop once to create it

Mac

Standard Path: ~/Library/Application Support/Claude/claude_desktop_config.json

Full Path: /Users/[YourUsername]/Library/Application Support/Claude/claude_desktop_config.json

How to access:

1. Open Finder
2. Press Cmd + Shift + G
3. Enter ~/Library/Application Support/Claude
4. Look for claude_desktop_config.json

Show hidden files: Press Cmd + Shift + . in Finder

Linux

Standard Path: ~/.config/Claude/claude_desktop_config.json

Alternative Paths:

• ~/.claude/claude_desktop_config.json
• $XDG_CONFIG_HOME/claude/claude_desktop_config.json

How to access:

# Navigate to config directory
cd ~/.config/Claude

# List files
ls -la

# Edit with your preferred editor
nano claude_desktop_config.json

Step 2: Understand Configuration Structure

The Claude Desktop configuration file uses this structure:

{
  "mcpServers": {
    "server-name": {
      "command": "executable-command",
      "args": ["argument1", "argument2"],
      "env": {
        "ENVIRONMENT_VARIABLE": "value"
      }
    }
  }
}

Example Empty Configuration

If your file is empty or doesn’t exist, start with:

{
  "mcpServers": {}
}

Example with Existing Servers

If you already have other MCP servers:

{
  "mcpServers": {
    "existing-server": {
      "command": "some-command",
      "args": ["--option", "value"]
    }
  }
}

Step 3: Add Desktop Commander Configuration

Add Desktop Commander to your configuration file:

Method 1: NPX Configuration (Recommended)

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

Method 2: Global Installation

If you prefer a global installation:

First, install globally:

npm install -g @wonderwhy-er/desktop-commander

Then configure:

{
  "mcpServers": {
    "desktop-commander": {
      "command": "desktop-commander"
    }
  }
}

Method 3: Local Installation with Custom Path

For local project-specific installations:

# In your project directory
npm install @wonderwhy-er/desktop-commander

Configuration:

{
  "mcpServers": {
    "desktop-commander": {
      "command": "node",
      "args": ["/path/to/your/project/node_modules/@wonderwhy-er/desktop-commander/dist/index.js"]
    }
  }
}

Step 4: Advanced Configuration Options

Environment Variables

Add custom environment variables:

{
  "mcpServers": {
    "desktop-commander": {
      "command": "npx",
      "args": ["-y", "@wonderwhy-er/desktop-commander"],
      "env": {
        "DEBUG": "desktop-commander:*",
        "NODE_ENV": "production",
        "DESKTOP_COMMANDER_LOG_LEVEL": "info"
      }
    }
  }
}

Custom Arguments

Pass custom arguments to Desktop Commander:

{
  "mcpServers": {
    "desktop-commander": {
      "command": "npx",
      "args": [
        "-y", 
        "@wonderwhy-er/desktop-commander",
        "--config-path",
        "/custom/config/path",
        "--log-level",
        "debug"
      ]
    }
  }
}

Security Configuration

Configure security settings through environment:

{
  "mcpServers": {
    "desktop-commander": {
      "command": "npx",
      "args": ["-y", "@wonderwhy-er/desktop-commander"],
      "env": {
        "ALLOWED_DIRECTORIES": "/home/user/projects,/home/user/documents",
        "BLOCKED_COMMANDS": "rm,sudo,format",
        "FILE_READ_LIMIT": "1000",
        "FILE_WRITE_LIMIT": "50"
      }
    }
  }
}

Step 5: Validate Configuration

JSON Syntax Validation

Ensure your JSON is valid:

1. Use a JSON validator (online tools available)
2. Check brackets and commas - every { needs a }
3. Verify quotes - all strings must be in double quotes
4. No trailing commas - JSON doesn’t allow trailing commas

Common JSON Errors

// ❌ WRONG - Missing comma
{
  "mcpServers": {
    "server1": {...}
    "server2": {...}  // Missing comma after server1
  }
}

// ❌ WRONG - Trailing comma
{
  "mcpServers": {
    "desktop-commander": {...},  // Trailing comma
  }
}

// ✅ CORRECT
{
  "mcpServers": {
    "server1": {...},
    "server2": {...}
  }
}

Configuration Testing

Test your configuration with a JSON validator:

Command Line (if jq is installed):

cat claude_desktop_config.json | jq .

Online Validators: Search for “JSON validator” and paste your configuration

Step 6: Test Installation

1. Save Configuration

   Save your claude_desktop_config.json file with the new Desktop Commander configuration

2. Close Claude Desktop

   Completely close Claude Desktop (check system tray/menu bar)

3. Restart Claude Desktop

   Open Claude Desktop fresh

4. Test Basic Functionality

   Try a simple command:

   Can you list the files in my home directory?
   

If Claude shows file listings, your manual installation was successful!

Step 7: Configure Security Settings

After successful installation, configure security settings:

Using Claude Commands

Ask Claude to configure security settings:

"Show me the current Desktop Commander configuration"
"Set the allowed directories to only my home directory"
"What commands are currently blocked for security?"

Manual Security Configuration

Create a Desktop Commander config file in your user directory:

Location: ~/.desktop-commander/config.json (or %USERPROFILE%\.desktop-commander\config.json on Windows)

{
  "allowedDirectories": [
    "/home/username/projects",
    "/home/username/documents"
  ],
  "blockedCommands": [
    "rm", "sudo", "format", "fdisk", "mkfs",
    "shutdown", "reboot", "passwd", "useradd"
  ],
  "fileReadLineLimit": 1000,
  "fileWriteLineLimit": 50,
  "telemetryEnabled": false
}

Troubleshooting Manual Installation

Claude doesn't recognize Desktop Commander

Check these common issues:

1. Configuration file syntax: Validate JSON with a validator
2. File location: Ensure config is in correct Claude directory
3. Node.js path: Verify npx command works in terminal
4. Case sensitivity: Check exact spelling of “desktop-commander”
5. Claude restart: Completely restart Claude Desktop

Permission errors during startup

Possible causes:

1. Node.js permissions: NPX may need to download packages
2. File permissions: Check Claude config directory permissions
3. Firewall/antivirus: Some security software blocks NPX
4. Corporate networks: Proxy settings may interfere with NPM

Desktop Commander starts but doesn't work

Debugging steps:

1. Check logs: Look for error messages in Claude Desktop
2. Test Node.js: Run npx @wonderwhy-er/desktop-commander --version in terminal
3. Environment variables: Check if custom env vars are correct
4. Path issues: Verify all paths in configuration exist

Configuration file gets overwritten

Prevention strategies:

1. Backup configuration: Keep a copy of your config file
2. File permissions: Make config file read-only if needed
3. Version control: Track changes with git
4. Documentation: Document your custom settings

Advanced Manual Setup

Multiple Desktop Commander Instances

Run multiple instances with different configurations:

{
  "mcpServers": {
    "desktop-commander-safe": {
      "command": "npx",
      "args": ["-y", "@wonderwhy-er/desktop-commander"],
      "env": {
        "ALLOWED_DIRECTORIES": "/home/user/safe-projects"
      }
    },
    "desktop-commander-dev": {
      "command": "npx", 
      "args": ["-y", "@wonderwhy-er/desktop-commander"],
      "env": {
        "ALLOWED_DIRECTORIES": "/home/user/development",
        "DEBUG": "desktop-commander:*"
      }
    }
  }
}

Custom Installation Path

Install Desktop Commander to a specific location:

# Create custom directory
mkdir -p ~/.local/share/desktop-commander
cd ~/.local/share/desktop-commander

# Install locally
npm install @wonderwhy-er/desktop-commander

# Configure Claude to use local installation

Configuration:

{
  "mcpServers": {
    "desktop-commander": {
      "command": "node",
      "args": [
        "/home/username/.local/share/desktop-commander/node_modules/@wonderwhy-er/desktop-commander/dist/index.js"
      ]
    }
  }
}

Development Mode Configuration

For development and debugging:

{
  "mcpServers": {
    "desktop-commander-dev": {
      "command": "npx",
      "args": ["-y", "@wonderwhy-er/desktop-commander@latest"],
      "env": {
        "DEBUG": "desktop-commander:*",
        "NODE_ENV": "development",
        "DESKTOP_COMMANDER_LOG_LEVEL": "debug",
        "DESKTOP_COMMANDER_TELEMETRY": "false"
      }
    }
  }
}

Maintenance and Updates

Manual Updates

Update Desktop Commander manually:

# For NPX installations (automatic)
# NPX always uses latest version, no manual update needed

# For global installations
npm update -g @wonderwhy-er/desktop-commander

# For local installations  
cd /path/to/installation
npm update @wonderwhy-er/desktop-commander

Configuration Backup

Keep backups of your configuration:

# Create backup
cp ~/.config/Claude/claude_desktop_config.json ~/.config/Claude/claude_desktop_config.json.backup

# With timestamp
cp ~/.config/Claude/claude_desktop_config.json ~/.config/Claude/claude_desktop_config.json.$(date +%Y%m%d)

Version Pinning

Pin to a specific version for stability:

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

Next Steps

Security Configuration

Fine-tune security settings for your manual installation

Advanced Usage

Explore advanced development workflows

Troubleshooting

Get help with configuration issues

Community

Share your manual setup experience with others