JameDesktopCommander

Production-grade MCP orchestration for local desktop automation and development.

JameDesktopCommander (JDC) is an independent fork of wonderwhy-er/DesktopCommanderMCP. The source tree temporarily retains upstream npm and MCP Registry identifiers for compatibility while the fork is under active development. JDC does not publish to upstream-owned namespaces.

Table of Contents

• Background

• Install

• Usage

• Windows Secure MCP Tunnel Lifecycle

• Windows UI Bridge Lifecycle

• Features

• Getting Started

• File Preview UI & Markdown Editor

• Handling Long-Running Commands

• Work in Progress and TODOs

• Frequently Asked Questions

• Data Collection & Privacy

• Maintainers

• Contributing

• License

JameDesktopCommander brings local development, automation, process control, OpenCode orchestration, and desktop interaction into one MCP surface. It remains compatible with the upstream Desktop Commander architecture while adding JDC-specific runtime, security, and governance layers.

Related MCP server: Desktop Commander MCP

Background

JameDesktopCommander extends Desktop Commander MCP with production-oriented Windows runtime integration, OpenCode orchestration, semantic Computer Use foundations, OpenAI Secure MCP Tunnel lifecycle management, and enforceable repository governance. Linux remains a planned first-class platform rather than a compatibility afterthought.

The project preserves upstream architecture where doing so keeps synchronization practical while deliberately diverging where JDC requires stronger Windows lifecycle, security, testing, or release guarantees. Its intellectual provenance is wonderwhy-er/DesktopCommanderMCP, licensed under MIT.

The intended repository identity is JameDesktopCommander. The inherited npm package @wonderwhy-er/desktop-commander and MCP Registry identifier are transitional metadata only; they belong to upstream and are not publication targets for JDC.

Install

JameDesktopCommander is not yet published to npm or the MCP Registry. For the current development line, install dependencies and build from a checked-out JDC source tree:

npm ci
npm run build
node dist/index.js --help

JDC requires Node.js 22.19.0 or newer. By default, runtime configuration remains in ~/.claude-server-commander. Managed deployments can override only the configuration root with --config-dir <path> or DESKTOP_COMMANDER_CONFIG_DIR=<path>; the CLI option takes precedence over the environment variable. These explicit boundaries are also used by CI so verification never needs to replace the operator's HOME or USERPROFILE.

The inherited installation examples below install upstream Desktop Commander, not JDC. They are retained temporarily as compatibility reference while JDC establishes its own publication namespaces.

Upstream compatibility reference

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.

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

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

This script handles all dependencies and configuration automatically.

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

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

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

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 or remove the entry from your claude_desktop_config.json

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

Restart Claude if running.

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

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.

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

macOS/Linux:

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

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

Windows PowerShell:

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

Troubleshooting: 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)

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

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:

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.

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

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.

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.

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

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.

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

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

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.

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.

Add to ~/.gemini/settings.json:

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

See Gemini CLI docs for more info.

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.

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.

Use Desktop Commander from ChatGPT, Claude web, and other AI services while commands still execute on your computer.

Start the Remote Device:

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

On first run, complete browser authentication, then connect your AI at mcp.desktopcommander.app.

• Stop the local device temporarily with Ctrl+C

• See available CLI options with npx @wonderwhy-er/desktop-commander@latest remote --help

• See Remote MCP setup, logout/revocation, CLI reference, and troubleshooting

Security

• ✅ The Remote Device only accepts commands while it is running

• ✅ Commands execute locally under your user permissions

• ✅ Secure OAuth authentication and encrypted communication channel

Usage

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

Windows Secure MCP Tunnel Lifecycle

On Windows, JDC manages the OpenAI Secure MCP Tunnel through a least-privilege Scheduled Task. The lifecycle uses the official tunnel-client binary and validates configuration with tunnel-client doctor before registration.

node dist/index.js tunnel install --tunnel-client-bin C:\path\to\tunnel-client.exe --profile-dir C:\path\to\profiles --profile profile-name
node dist/index.js tunnel start
node dist/index.js tunnel status
node dist/index.js tunnel restart
node dist/index.js tunnel stop
node dist/index.js tunnel uninstall

tunnel install registers both the tunnel task and a least-privilege JameDesktopCommander Tunnel Restart Supervisor task. The supervisor has no automatic trigger and runs outside the tunnel process tree. tunnel restart starts only that supervisor; the worker captures the registered tunnel-client process tree through Windows CIM, requests Task Scheduler to stop the tunnel task, terminates only captured survivors with the native taskkill.exe /T /F, starts a fresh task instance, and requires a new tunnel process plus a fully healthy control-plane poll before reporting success.

tunnel status discovers the registered executable and profile from Task Scheduler, resolves the profile through tunnel-client profiles list --json, and delegates liveness/readiness checks to tunnel-client health --json --require-control-plane-poll. JDC does not hardcode the dynamic health port and does not read secret file contents.

Windows UI Bridge Lifecycle

On Windows, the read-only computer_inspect tool uses the JameDesktopCommander UI bridge to inspect the foreground application through UI Automation. The bridge must run in the owning user's interactive session; it does not use coordinate guessing and this lifecycle does not enable click or type actions.

Build or obtain DesktopCommander.UiBridge.exe, place it at a durable absolute path, then register and control its Scheduled Task through the JDC CLI:

node dist/index.js ui-bridge install --bridge-exe C:\path\to\DesktopCommander.UiBridge.exe
node dist/index.js ui-bridge start
node dist/index.js ui-bridge stop
node dist/index.js ui-bridge uninstall

ui-bridge install registers the task but does not copy or relocate the executable. Replacing an existing JameDesktopCommander UI Bridge task is fail-closed and requires an explicit --force. The task uses least privilege, an interactive-token principal, and a per-user logon trigger.

Available Tools

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
content to find
=======
new content
>>>>>>> REPLACE

Example:

src/main.js
<<<<<<< SEARCH
console.log("old message");
=======
console.log("new message");
>>>>>>> REPLACE

Enhanced Edit Block Features

The edit_block tool includes several enhancements for better reliability:

1. Improved Prompting: Tool descriptions now emphasize making multiple small, focused edits rather than one large change

2. Fuzzy Search Fallback: When exact matches fail, it performs fuzzy search and provides detailed feedback

3. Character-level Diffs: Shows exactly what's different using {-removed-}{+added+} format

4. Multiple Occurrence Support: Can replace multiple instances with expected_replacements parameter

5. Comprehensive Logging: All fuzzy searches are logged for analysis and debugging

When a search fails, you'll see detailed information about the closest match found, including similarity percentage, execution time, and character differences. All these details are automatically logged for later analysis using the fuzzy search log tools.

Docker Support

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

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/overview

   • 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

Features

• Remote AI Control - Use Desktop Commander from ChatGPT, Claude web, and other AI services via Remote MCP

• File Preview UI - Optional interactive previews through explicit render tools (preview_file, render_directory, render_config_editor) so ordinary data operations stay lightweight

• Enhanced terminal commands with interactive process control

• Execute code in memory (Python, Node.js, R) without saving files

• Instant data analysis - just ask to analyze CSV/JSON/Excel files

• Native Excel file support - Read, write, edit, and search Excel files (.xlsx, .xls, .xlsm) without external tools

• PDF support - Read PDFs with text extraction, create new PDFs from markdown, modify existing PDFs

• DOCX support - Read, create, edit, and search Word documents (.docx) with surgical XML editing and markdown-to-DOCX conversion

• Interact with running processes (SSH, databases, development servers)

• Execute terminal commands with output streaming

• Command timeout and background execution support

• Process management (list and kill processes)

• Session management for long-running commands

• Process output pagination - Read terminal output with offset/length controls to prevent context overflow

• Server configuration management:

  • Get/set configuration values

  • Update multiple settings at once

  • Dynamic configuration changes without server restart

• Full filesystem operations:

  • Read/write files (text, Excel, PDF, DOCX)

  • Create/list directories

  • Recursive directory listing with configurable depth and context overflow protection for large folders

  • Move files/directories

  • Search files and content (including Excel content)

  • Get file metadata

  • Negative offset file reading: Read from end of files using negative offset values (like Unix tail)

• Code editing capabilities:

  • Surgical text replacements for small changes

  • Full file rewrites for major changes

  • Multiple file support

  • Pattern-based replacements

  • vscode-ripgrep based recursive code or text search in folders

• Local tool-call history and audit logs:

  • Tool calls and arguments are recorded locally on the machine running Desktop Commander

  • Recent call history with bounded output previews is available through get_recent_tool_calls

  • Size-based rotation/trimming keeps the active history files bounded

• Safety guardrails (not a sandbox — see SECURITY.md):

  • Symlink traversal prevention on file operations

  • Command blocklist for accidental execution

  • Docker isolation for complete isolation

Updating & Uninstalling Desktop Commander

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:

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, remove the "desktop-commander" entry from the "mcpServers" section, and 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!

🚀 New User Onboarding

Desktop Commander includes intelligent onboarding to help you discover what's possible:

For New Users: When you're just getting started (fewer than 10 successful commands), Claude will automatically offer helpful getting-started guidance and practical tutorials after you use Desktop Commander successfully.

Request Help Anytime: You can ask for onboarding assistance at any time by simply saying:

• "Help me get started with Desktop Commander"

• "Show me Desktop Commander examples"

• "What can I do with Desktop Commander?"

Claude will then show you beginner-friendly tutorials and examples, including:

• 📁 Organizing your Downloads folder automatically

• 📊 Analyzing CSV/Excel files with Python

• ⚙️ Setting up GitHub Actions CI/CD

• 🔍 Exploring and understanding codebases

• 🤖 Running interactive development environments

URL Support

• read_file can now fetch content from both local files and URLs

• Example: read_file with isUrl: true parameter to read from web resources

• Handles both text and image content from remote sources

• Images (local or from URLs) are displayed visually in Claude's interface, not as text

• Claude can see and analyze the actual image content

• Default 30-second timeout for URL requests

File Preview UI & Markdown Editor

JameDesktopCommander keeps ordinary data/action tools lightweight and exposes rich UI only through explicit render tools. read_file, list_directory, get_config, and write/edit operations do not mount an iframe by default; use preview_file, render_directory, or render_config_editor when an interactive view is useful.

Render tools follow the MCP Apps result flow: the initial tool result carries the structured data needed by the view, so mounting a preview does not immediately issue a second filesystem read. Follow-up tool calls are reserved for explicit refresh, navigation, editing, or compatibility fallback behavior. UI resources use versioned URIs so incompatible view revisions do not reuse a stale host cache entry.

Supported file types

• Markdown — rendered preview with a built-in editor

• Images — inline display (PNG, JPEG, GIF, WebP, etc.)

• Code files — syntax-highlighted source view

• HTML — rendered preview with toggle to source view

• Directories — interactive tree with expand/collapse and lazy loading

• PDF, Excel, DOCX — native content extraction and display

Markdown Editor

When preview_file renders a .md file in a compatible MCP Apps host, you can edit it directly inside the preview panel — no need to open a separate app.

How to use:

1. Ask your AI client to preview the markdown file with preview_file

2. Expand the file preview to fullscreen using the ⤢ Expand button

3. The editor activates automatically in fullscreen mode

4. Edit your content with a live preview toggle, copy, undo, and save controls

5. Changes are saved back to disk; collapse to return to inline view

Editor features:

• Live edit / preview toggle — switch between raw markdown and rendered output

• Auto-save to disk with save status indicator

• Undo support to revert unsaved changes

• Copy button to grab the full markdown source

• Open in editor — launch your default markdown app directly from the panel

• Partial-file awareness — loads and merges surrounding lines when the file was only partially read

• Text selection context — select text in preview mode and the AI can reference your selection

Directory Browser

list_directory returns a model-facing directory listing without mounting UI. Use render_directory when you want the same path opened as an interactive file tree inside the preview panel.

Features:

• Expandable tree — folders expand and collapse on click; top-level contents shown immediately

• Lazy loading — subfolders load on demand to keep the initial view fast

• Large directory handling — directories with many items show a ⚠ click to load all button instead of overwhelming the view

• Open in Finder/Explorer — each folder has a quick-open button to reveal it in your file manager

• Click to preview — clicking any file in the tree opens it in the file preview panel directly

• Back navigation — after opening a file from the tree, a ← Back button returns you to the directory view

Other preview features

• Expand / collapse — toggle between compact summary row and full panel

• Open in folder — reveal the file in Finder/Explorer with one click

• Load more lines — incrementally load content above or below a partial read window

• Text selection — highlight text in any preview; the AI can see and reference your selection

Fuzzy Search Log Analysis (npm scripts)

The fuzzy search logging system includes convenient npm scripts for analyzing logs outside of the MCP environment:

# View recent fuzzy search logs
npm run logs:view -- --count 20

# Analyze patterns and performance
npm run logs:analyze -- --threshold 0.8

# Export logs to CSV or JSON
npm run logs:export -- --format json --output analysis.json

# Clear all logs (with confirmation)
npm run logs:clear

Fuzzy Search Logs

Desktop Commander includes comprehensive logging for fuzzy search operations in the edit_block tool. When an exact match isn't found, the system performs a fuzzy search and logs detailed information for analysis.

What Gets Logged

Every fuzzy search operation logs:

• Search and found text: The text you're looking for vs. what was found

• Similarity score: How close the match is (0-100%)

• Execution time: How long the search took

• Character differences: Detailed diff showing exactly what's different

• File metadata: Extension, search/found text lengths

• Character codes: Specific character codes causing differences

Log Location

Logs are automatically saved to:

• macOS/Linux: ~/.claude-server-commander-logs/fuzzy-search.log

• Windows: %USERPROFILE%\.claude-server-commander-logs\fuzzy-search.log

What You'll Learn

The fuzzy search logs help you understand:

1. Why exact matches fail: Common issues like whitespace differences, line endings, or character encoding

2. Performance patterns: How search complexity affects execution time

3. File type issues: Which file extensions commonly have matching problems

4. Character encoding problems: Specific character codes that cause diffs

Local Tool History and Audit Logs

Desktop Commander keeps tool-call records locally on the machine running the MCP server. These local files are separate from optional telemetry and are not a server-side historical audit log.

claude_tool_call.log — local argument log

Every tool call handled by the local MCP server is appended as a text line containing an ISO timestamp, the tool name, and the JSON-serialized arguments. Arguments are not redacted or sanitized before being written to this local file, so it may contain command text, file paths, or other sensitive values passed to tools. Tool outputs are not written to this file.

The active file rotates when it reaches 10 MB. The previous file is renamed using a timestamp, for example claude_tool_call_2026-09-07_14-32-10.log, and a new claude_tool_call.log is created. Rotated files are not automatically deleted by the logger.

Locations:

• macOS/Linux: ~/.claude-server-commander/claude_tool_call.log

• Windows: %USERPROFILE%\.claude-server-commander\claude_tool_call.log

tool-history.jsonl — recent tool-call history

Desktop Commander also keeps a JSON Lines history used by get_recent_tool_calls. Each record contains the timestamp, tool name, arguments, duration, and the returned result. This history is loaded from disk on startup, so recent history can survive an MCP server restart.

To keep this history bounded:

• At most the most recent 1,000 calls are kept in memory.

• Stored output is capped at 4 KiB per record; larger outputs are replaced with an omission marker.

• The on-disk file is trimmed when it grows beyond 5 MiB, keeping roughly the newest 4 MiB.

• On startup, a history with more than 2,000 records is rewritten to the most recent 1,000 records.

• get_recent_tool_calls and track_ui_event are excluded from this JSONL history.

Locations:

• macOS/Linux: ~/.claude-server-commander/tool-history.jsonl

• Windows: %USERPROFILE%\.claude-server-commander\tool-history.jsonl

Remote calls and server-side retention

Calls executed through Remote Desktop Commander are still handled by the local MCP server and use the same local history files above. The Remote Desktop Commander service temporarily stores tool arguments and results in mcp_remote_calls so calls can be routed and completed. Terminal rows are automatically swept shortly after completion (eligible for deletion after one minute, with a one-hour creation-time backstop), so they are not kept as a long-term historical server-side audit trail.

These local history files are also separate from Desktop Commander's optional telemetry. The files themselves are not uploaded as telemetry. See Data Collection & Privacy and PRIVACY.md for telemetry details.

Handling Long-Running Commands

For commands that may take a while:

Configuration Management

⚠️ Important Security Warnings

For comprehensive security information and vulnerability reporting: See SECURITY.md

1. Known security limitations: Directory restrictions and command blocking can be bypassed through various methods including symlinks, command substitution, and absolute paths or code execution

2. Always change configuration in a separate chat window from where you're doing your actual work. Claude may sometimes attempt to modify configuration settings (like allowedDirectories) if it encounters filesystem access restrictions.

3. The allowedDirectories setting currently only restricts filesystem operations, not terminal commands. Terminal commands can still access files outside allowed directories.

4. For production security: Use the Docker installation which provides complete isolation from your host system.

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

Best Practices

1. Create a dedicated chat for configuration changes: Make all your config changes in one chat, then start a new chat for your actual work.

2. Be careful with empty allowedDirectories: Setting this to an empty array ([]) grants access to your entire filesystem for file operations.

3. Use specific paths: Instead of using broad paths like /, specify exact directories you want to access.

4. Always verify configuration after changes: Use get_config({}) to confirm your changes were applied correctly.

Command Line Options

Desktop Commander supports several command line options for customizing behavior:

Disable Onboarding

By default, Desktop Commander shows helpful onboarding prompts to new users (those with fewer than 10 tool calls). You can disable this behavior:

# Disable onboarding for this session
node dist/index.js --no-onboarding

# Or if using npm scripts
npm run start:no-onboarding

# 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"

Using Different Shells

You can specify which shell to use for command execution:

// Using default shell (bash or system default)
execute_command({ "command": "echo $SHELL" })

// Using zsh specifically
execute_command({ "command": "echo $SHELL", "shell": "/bin/zsh" })

// Using bash specifically
execute_command({ "command": "echo $SHELL", "shell": "/bin/bash" })

This allows you to use shell-specific features or maintain consistent environments across commands.

1. execute_command returns after timeout with initial output

2. Command continues in background

3. Use read_output with PID to get new output

4. Use force_terminate to stop if needed

Debugging

If you need to debug the server, you can install it in debug mode:

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

# 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

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.

What is Desktop Commander?

It's an MCP tool that enables Claude Desktop to access your file system and terminal, turning Claude into a versatile assistant for coding, automation, codebase exploration, and more.

How is this different from Cursor/Windsurf?

Unlike IDE-focused tools, Claude Desktop Commander provides a solution-centric approach that works with your entire OS, not just within a coding environment. Claude reads files in full rather than chunking them, can work across multiple projects simultaneously, and executes changes in one go rather than requiring constant review.

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.

Does Desktop Commander automatically update?

Yes, when installed through npx or Smithery, Desktop Commander automatically updates to the latest version when you restart Claude. No manual update process is needed.

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

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.

How do I report security vulnerabilities?

Please create a GitHub Issue with detailed information about any security vulnerabilities you discover. See our Security Policy for complete guidelines on responsible disclosure.

Data Collection & Privacy

Desktop Commander collects limited, pseudonymous telemetry to improve the tool. We do not collect file contents, file paths, or command arguments as telemetry.

This is separate from the local tool history and audit logs, which stay on the machine running Desktop Commander and may contain tool arguments and bounded result previews.

Opt-out: Ask Claude to "disable Desktop Commander telemetry" or set "telemetryEnabled": false in your config.

For complete details, see our Privacy Policy.

Maintainers

• Roy Mejía — JameDesktopCommander maintainer.

• Eduards Ruzga — upstream Desktop Commander author.

Contributing

Pull requests are accepted. Read CONTRIBUTING.md before creating commits or a pull request; it defines the enforced Commitlint, Husky, PR-body, CI, squash-merge, and release contracts. JDC-specific questions and defects belong in the JameDesktopCommander repository once its public remote is created. Upstream-specific issues should continue to be reported upstream.

License

MIT