NPX Installation

Install Desktop Commander directly using NPX for more control over the process

NPX Installation

Install Desktop Commander directly using NPX for users who want more control over the installation process or prefer not to use Smithery.

When to Use NPX Installation

Direct Control

Full control over the installation process and configuration

Latest Version

Always gets the most current version directly from npm registry

Interactive Setup

Guided setup wizard walks you through configuration options

Custom Configuration

Ability to customize installation parameters and settings

Prerequisites

Before installing, ensure you have:

• Claude Desktop installed from claude.ai/download
• Claude Pro or Max subscription (required for Desktop Commander)
• Node.js v18.18.0+ from nodejs.org

Installation Command

1. Open Terminal/Command Prompt

   Windows: Press Win + R, type cmd, press Enter

   Mac: Press Cmd + Space, type “Terminal”, press Enter

   Linux: Open your terminal application

2. Run NPX Install Command

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

   This downloads and runs the latest setup wizard

3. Follow Interactive Setup

   The setup wizard will guide you through:

   • Configuration file detection
   • Security settings selection
   • Installation confirmation
   • Initial configuration
4. Restart Claude Desktop

   Close Claude Desktop completely and reopen it

Interactive Setup Process

The NPX setup wizard provides guided installation:

Step 1: Configuration Detection

🔍 Checking for Claude Desktop configuration...
✓ Found configuration at: ~/.config/claude/claude_desktop_config.json
✓ Configuration file is valid JSON

Step 2: Installation Options

📦 Desktop Commander Installation Options:

1. Standard installation (recommended)
2. Custom security settings
3. Directory restrictions
4. Advanced configuration

Select option (1-4): 1

Step 3: Security Configuration

🔒 Security Settings:

File access level:
1. Home directory only (safest)
2. Full system access (advanced users)
3. Custom directory list

Select option (1-3): 1

Step 4: Installation Confirmation

📋 Installation Summary:

Installation method: NPX direct
Security level: Home directory only
Configuration file: ~/.config/claude/claude_desktop_config.json
Auto-updates: Enabled

Proceed with installation? (y/N): y

Step 5: Completion

✅ Desktop Commander installed successfully!

Next steps:
1. Restart Claude Desktop
2. Test with: "Can you list my home directory files?"

Configuration saved to: ~/.config/claude/claude_desktop_config.json

Manual Configuration Alternative

If you prefer to configure manually after installation:

1. Install Without Setup

   npx @wonderwhy-er/desktop-commander@latest --no-setup
   
2. Add to Claude Configuration

   Edit your claude_desktop_config.json file and add:

   {
     "mcpServers": {
       "desktop-commander": {
         "command": "npx",
         "args": ["-y", "@wonderwhy-er/desktop-commander"]
       }
     }
   }
   
3. Restart Claude Desktop

   Close and reopen Claude Desktop

Configuration File Locations

NPX setup automatically detects your Claude configuration:

Windows

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

Full Path Example: C:\Users\YourName\AppData\Roaming\Claude\claude_desktop_config.json

Alternative Locations:

• %USERPROFILE%\.claude\claude_desktop_config.json
• Custom installation directories

Mac

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

Full Path Example: /Users/YourName/Library/Application Support/Claude/claude_desktop_config.json

Alternative Locations:

• ~/.config/claude/claude_desktop_config.json
• Custom installation directories

Linux

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

Full Path Example: /home/username/.config/Claude/claude_desktop_config.json

Alternative Locations:

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

Automatic Updates

NPX installations automatically update when you restart Claude Desktop:

How Auto-Updates Work

• Each Claude restart checks for new versions
• Updates happen automatically in the background
• No manual update commands needed
• Always runs the latest stable version

Controlling Updates

If you want to pin a specific version:

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

Verification

Test your NPX installation:

1. Basic File Access Test

   Can you show me the contents of my home directory?
   
2. Advanced Functionality Test

   Can you create a test file called "desktop-commander-test.txt" with today's date?
   
3. Process Execution Test

   Can you run the command "date" and show me the output?
   

If all tests pass, your NPX installation is working correctly!

NPX vs Other Installation Methods

Feature	NPX	Smithery	Manual
Ease of Use	Medium	High	Low
Customization	High	Medium	Highest
Auto-Updates	Yes	Yes	No
Error Recovery	Basic	Advanced	None
Setup Wizard	Yes	No	No

Troubleshooting NPX Installation

NPX command not found

NPX is included with Node.js. If not available:

1. Verify Node.js installation: node --version
2. Reinstall Node.js from nodejs.org
3. Restart terminal after installation
4. Check PATH environment variable includes Node.js

Setup wizard fails to detect Claude

1. Ensure Claude Desktop has been run at least once
2. Check if Claude is installed in a custom location
3. Run setup with debug flag: --debug
4. Manually specify config path: --config-path="/path/to/config"

Permission denied during installation

1. Don’t use sudo with NPX/NPM commands
2. Check file permissions on Claude config directory
3. Run terminal as administrator (Windows only)
4. Use npx --yes to skip permission prompts

Network issues during download

1. Check internet connection and proxy settings
2. Configure NPM registry: npm config set registry https://registry.npmjs.org/
3. Clear NPM cache: npm cache clean --force
4. Try using a different network or VPN

Advanced NPX Options

Debug Mode

Get detailed installation information:

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

Custom Config Path

Specify a custom Claude configuration location:

npx @wonderwhy-er/desktop-commander@latest setup --config-path="/custom/path"

Skip Interactive Prompts

Use default settings for automated installations:

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

Security-First Installation

Install with maximum security restrictions:

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

Next Steps

Configure Security

Customize your security settings and permissions

Quick Start Guide

Learn basic usage with practical examples

Use Cases

Discover what you can accomplish with Desktop Commander

Troubleshooting

Get help with installation issues