> ## Documentation Index
> Fetch the complete documentation index at: https://desktopcommander.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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**:

```bash theme={null}
# 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "mcpServers": {}
}
```

### Example with Existing Servers

If you already have other MCP servers:

```json theme={null}
{
  "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)

```json theme={null}
{
  "mcpServers": {
    "desktop-commander": {
      "command": "npx",
      "args": ["-y", "@wonderwhy-er/desktop-commander"]
    }
  }
}
```

### Method 2: Global Installation

If you prefer a global installation:

First, install globally:

```bash theme={null}
npm install -g @wonderwhy-er/desktop-commander
```

Then configure:

```json theme={null}
{
  "mcpServers": {
    "desktop-commander": {
      "command": "desktop-commander"
    }
  }
}
```

### Method 3: Local Installation with Custom Path

For local project-specific installations:

```bash theme={null}
# In your project directory
npm install @wonderwhy-er/desktop-commander
```

Configuration:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

```json theme={null}
// ❌ 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)**:

```bash theme={null}
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?
```

> [!TIP]
>
> 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)

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```bash theme={null}
# 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

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

## Next Steps

> **[Security Configuration](https://desktopcommander.mintlify.site/tools/system/get-config.md)**
>
> Fine-tune security settings for your manual installation

> **[Advanced Usage](https://desktopcommander.mintlify.site/use-cases/development.md)**
>
> Explore advanced development workflows

> **[Troubleshooting](https://desktopcommander.mintlify.site/support/troubleshooting.md)**
>
> Get help with configuration issues

> **[Community](https://desktopcommander.mintlify.site/support/discord.md)**
>
> Share your manual setup experience with others


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.