Skip to content

Docker installation #199

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
wonderwhy-er merged 17 commits into from
Aug 12, 2025
Merged

Docker installation #199

Show file tree
Hide file tree
Changes from 12 commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
21692e7
Docker install
wonderwhy-er Jul 23, 2025
e0fca22
Improved messages
wonderwhy-er Jul 23, 2025
b0d1ab2
Mac script and readme update
wonderwhy-er Aug 6, 2025
487901d
Mac and readme updates
wonderwhy-er Aug 7, 2025
1536d0b
Improve reset command
wonderwhy-er Aug 7, 2025
18704aa
Docker mounted folder detection
wonderwhy-er Aug 7, 2025
43e1486
First working windows script, needs more work
wonderwhy-er Aug 8, 2025
479e558
More or less full working script for windows
wonderwhy-er Aug 8, 2025
5a7b27c
Actually this is right script for Windows
wonderwhy-er Aug 8, 2025
7e63c40
Full script with restart
wonderwhy-er Aug 8, 2025
119dc73
Readme update
wonderwhy-er Aug 9, 2025
25f06b3
Readme update
wonderwhy-er Aug 9, 2025
5719125
Remove "in-docker" from mcp key name
wonderwhy-er Aug 11, 2025
ed368b4
Remove too technical things
wonderwhy-er Aug 11, 2025
e63aa9c
Change from mnt to home for user mounted folders
wonderwhy-er Aug 11, 2025
b359dff
Adjust prompts and paths for pasting host path in way that docker det…
wonderwhy-er Aug 12, 2025
17dfadc
Improve docker install progress for mac
wonderwhy-er Aug 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
174 changes: 163 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,6 @@ Work with code and text, run processes, and automate tasks, going far beyond oth
- [Features](#features)
- [How to install](#how-to-install)
- [Usage](#usage)
- [Docker Support](#docker-support)
- [Handling Long-Running Commands](#handling-long-running-commands)
- [Work in Progress and TODOs](#roadmap)
- [Sponsors and Supporters](#support-desktop-commander)
Expand Down Expand Up @@ -70,11 +69,12 @@ Execute long-running terminal commands on your computer and manage processes thr
- Detailed timestamps and arguments

## How to install
First, ensure you've downloaded and installed the [Claude Desktop app](https://claude.ai/download) and you have [npm installed](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).

> **📋 Update & Uninstall Information:** Before choosing an installation option, note that **only Options 1 and 3 have automatic updates**. Options 2, 4, and 5 require manual updates. See the sections below for update and uninstall instructions for each option.
Desktop Commander offers multiple installation methods to fit different user needs and technical requirements.

### Option 1: Install through npx ⭐ **Auto-Updates**
> **📋 Update & Uninstall Information:** Before choosing an installation option, note that **only Options 1, 2, 3, and 6 have automatic updates**. Options 4 and 5 require manual updates. See the sections below for update and uninstall instructions for each option.

### Option 1: Install through npx ⭐ **Auto-Updates** **Requires Node.js**
Just run this in terminal:
```
npx @wonderwhy-er/desktop-commander@latest setup
Expand All @@ -90,7 +90,7 @@ Restart Claude if running.
**🔄 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**
### Option 2: Using bash script installer (macOS) ⭐ **Auto-Updates** **Installs Node.js if needed**
For macOS users, you can use our automated bash installer which will check your Node.js version, install it if needed, and automatically configure Desktop Commander:
```
curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install.sh | bash
Expand All @@ -101,7 +101,7 @@ This script handles all dependencies and configuration automatically for a seaml
**🔄 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**
### Option 3: Installing via Smithery ⭐ **Auto-Updates** **Requires Node.js**

To install Desktop Commander for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@wonderwhy-er/desktop-commander):

Expand All @@ -113,7 +113,7 @@ npx -y @smithery/cli install @wonderwhy-er/desktop-commander --client claude
**🔄 Manual Update:** Re-run the Smithery install command
**🗑️ Uninstall:** `npx -y @smithery/cli uninstall @wonderwhy-er/desktop-commander --client claude`

### Option 4: Add to claude_desktop_config manually ⭐ **Auto-Updates**
### 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`
Expand All @@ -139,7 +139,7 @@ Restart Claude if running.
**🔄 Manual Update:** Run the setup command again
**🗑️ Uninstall:** Run `npx @wonderwhy-er/desktop-commander@latest remove` or remove the "desktop-commander" entry from your claude_desktop_config.json file

### Option 5: Checkout locally ❌ **Manual Updates**
### ### Option 5: Checkout locally ❌ **Manual Updates** **Requires Node.js** ❌ **Manual Updates** **Requires Node.js**

@coderabbitai coderabbitai Bot Aug 11, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Remove duplicate text in Option 5 heading

The heading has duplicate "❌ Manual Updates Requires Node.js" text.

Apply this fix:

-### ### Option 5: Checkout locally ❌ **Manual Updates** **Requires Node.js** ❌ **Manual Updates** **Requires Node.js**
+### Option 5: Checkout locally ❌ **Manual Updates** **Requires Node.js**
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
### ### Option 5: Checkout locally ❌ **Manual Updates** **Requires Node.js** ❌ **Manual Updates** **Requires Node.js**
### Option 5: Checkout locally ❌ **Manual Updates** **Requires Node.js**
🤖 Prompt for AI Agents 
In README.md around line 142, the Option 5 heading contains duplicated text ("❌
**Manual Updates** **Requires Node.js**") — remove the duplicate so the heading
reads once (e.g., "### Option 5: Checkout locally ❌ **Manual Updates**
**Requires Node.js**") and ensure spacing/markdown syntax remains correct.

1. Clone and build:
```bash
git clone https://github.com/wonderwhy-er/DesktopCommanderMCP.git
Expand All @@ -158,16 +158,168 @@ The setup command will:
**🔄 Manual Update:** `cd DesktopCommanderMCP && git pull && npm run setup`
**🗑️ Uninstall:** Run `npx @wonderwhy-er/desktop-commander@latest remove` or remove the cloned directory and remove MCP server entry from Claude config

### Option 6: Docker Installation 🐳 ⭐ **Auto-Updates** **No Node.js Required**

Perfect for users who want complete or partial isolation or don't have Node.js installed. Desktop Commander runs in a sandboxed Docker container with a persistent work environment.

#### Prerequisites
- [Docker Desktop](https://www.docker.com/products/docker-desktop/) installed **and running**
- Claude Desktop app installed

**Important:** Make sure Docker Desktop is fully started before running the installer.

#### Automated Installation (Recommended)

**macOS/Linux:**
```bash
bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh)
```

**Windows PowerShell (Run as Administrator):**
```powershell
# Download and run the installer (one-liner)
iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.ps1'))
```

The automated installer will:
- Check Docker installation
- Pull the latest Docker image
- Prompt you to select folders for mounting
- Configure Claude Desktop automatically
- Restart Claude if possible

#### How Docker Persistence Works
Desktop Commander creates a persistent work environment that remembers everything between sessions:
- **Your development tools**: Any software you install (Node.js, Python, databases, etc.) stays installed
- **Your configurations**: Git settings, SSH keys, shell preferences, and other personal configs are preserved
- **Your work files**: Projects and files in the workspace area persist across restarts
- **Package caches**: Downloaded packages and dependencies are cached for faster future installs

Think of it like having your own dedicated development computer that never loses your setup, but runs safely isolated from your main system.

#### Manual Docker Configuration

If you prefer manual setup, add this to your claude_desktop_config.json:

**Basic setup (no file access):**
```json
{
"mcpServers": {
"desktop-commander-in-docker": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"mcp/desktop-commander:latest"
]
}
}
}
```

**With folder mounting:**
```json
{
"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:**
```json
{
"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 Benefits
✅ **Controlled Isolation:** Runs in sandboxed environment with persistent development state
✅ **No Node.js Required:** Everything included in the container
✅ **Cross-Platform:** Same experience on all operating systems
✅ **Persistent Environment:** Your tools, files, configs, and work survives restarts

**✅ Auto-Updates:** Yes - `latest` tag automatically gets newer versions
**🔄 Manual Update:** `docker pull mcp/desktop-commander:latest` then restart Claude

#### Docker Management Commands

**macOS/Linux:**

Check installation status:
```bash
bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh) --status
```

Reset all persistent data (removes all installed tools and configs):
```bash
bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh) --reset
```

**Windows PowerShell:**

Check status:
```powershell
$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:
```powershell
$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:
```powershell
$script = (New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.ps1'); & ([ScriptBlock]::Create("$script")) -Help
```

Verbose output:
```powershell
$script = (New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.ps1'); & ([ScriptBlock]::Create("$script")) -VerboseOutput
```

#### Troubleshooting Docker Installation
If you broke the Docker container or need a fresh start:
```bash
# 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)
```
This will completely reset your persistent environment and reinstall everything fresh with exception of not touching mounted folders

## Updating & Uninstalling Desktop Commander

### Automatic Updates (Options 1, 2, 3 & 4)
**Options 1 (npx), Option 2 (bash installer), 3 (Smithery) and Option 4 (manual config)** automatically update to the latest version whenever you restart Claude. No manual intervention needed.
### 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`

### Uninstalling Desktop Commander

#### 🤖 Automatic Uninstallation (Recommended)

The easiest way to completely remove Desktop Commander:
Expand Down
Loading