📌Overview

Purpose: The framework aims to enable the Claude desktop application to execute long-running terminal commands and manage processes effectively.

Overview: Desktop Commander MCP extends the functionalities of the Claude desktop app by integrating a Model Context Protocol server that allows for efficient terminal command execution and advanced file editing features. It enhances developer productivity by providing tools for process management, file operations, and code editing capabilities.

Key Features:

Execute Terminal Commands: Run terminal commands with support for output streaming, timeouts, and background execution, enabling real-time process management.
Filesystem Operations: Comprehensive file management capabilities including reading/writing files, creating directories, and performing surgical text replacements or full rewrites in code files, enhancing code editing tasks.

Desktop Commander MCP

Search, update, manage files and run terminal commands with AI

Short version: four key features — terminal commands, diff-based file editing, ripgrep-based text search in folders, and ability to read files from URLs.

Features
Installation
Usage
Handling Long-Running Commands
Work in Progress and TODOs
Media
Testimonials
Frequently Asked Questions
Contributing
License

This server allows the Claude desktop app to execute long-running terminal commands on your computer and manage processes through Model Context Protocol (MCP). It is built on top of the MCP Filesystem Server to provide additional search and replace file editing capabilities.

Features

Execute terminal commands with output streaming
Command timeout and background execution support
Process management (list and kill processes)
Session management for long-running commands
Server configuration management:
- Get/set configuration values
- Update multiple settings at once
- Dynamic configuration changes without server restart
Full filesystem operations:
- Read/write files
- Create/list directories
- Move files/directories
- Search files
- Get file metadata
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/text search in folders

Installation

First, ensure you've downloaded and installed the Claude Desktop app and have npm installed.

Option 1: Install through npx

Run 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

Restart Claude if running.

Option 2: Bash script installer (macOS)

For macOS users:

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

This script installs Node.js if needed and configures Desktop Commander automatically.

Option 3: Installing via Smithery

To install Desktop Commander for Claude Desktop automatically:

npx -y @smithery/cli install @wonderwhy-er/desktop-commander --client claude

Option 4: Add to claude_desktop_config manually

Add this entry to your claude_desktop_config.json:

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

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

Restart Claude if running.

Option 5: Checkout locally

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
Configure Claude's desktop app
Add MCP servers to Claude's config if needed

Updating Desktop Commander

If installed through npx or Smithery, it automatically updates on Claude restart. Manual installs require running the setup command again.

Usage

The server provides several tools categorized as follows:

Category	Tool	Description
Configuration	`get_config`	Get complete server configuration as JSON
	`set_config_value`	Set a configuration value by key (e.g. blockedCommands, defaultShell, allowedDirectories)
Terminal	`execute_command`	Execute terminal command with timeout and shell selection
	`read_output`	Read new output from running terminal session
	`force_terminate`	Force terminate a running terminal session
	`list_sessions`	List active terminal sessions
	`list_processes`	List running processes with details
	`kill_process`	Terminate a process by PID
Filesystem	`read_file`	Read contents from local filesystem or URLs
	`read_multiple_files`	Read multiple files concurrently
	`write_file`	Replace file contents completely
	`create_directory`	Create or ensure existence of a directory
	`list_directory`	Get detailed file and directory listing
	`move_file`	Move or rename files/directories
	`search_files`	Find files by case-insensitive substring matching
	`search_code`	Search text/code patterns using ripgrep
	`get_file_info`	Retrieve detailed file or directory metadata
Text Editing	`edit_block`	Apply surgical text replacements (best for changes under 20% of file size)

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

URL Support

read_file can fetch content from local files or URLs (text and images supported).
Images loaded locally or via URLs are displayed visually in Claude’s interface.
Default timeout for URL requests is 30 seconds.

Handling Long-Running Commands

execute_command returns after timeout with initial output.
Command continues running in background.
Use read_output with PID to fetch new output.
Use force_terminate to stop a command if required.

Configuration Management

Important Security Warnings

Always change configuration in a separate chat window from your main workflow to avoid unintended changes.
The allowedDirectories setting restricts filesystem operations but does not sandbox terminal commands.

Using Configuration Tools

// Get entire configuration
get_config({})

// Set a configuration value
set_config_value({ "key": "defaultShell", "value": "/bin/zsh" })

// Set multiple values via separate calls
set_config_value({ "key": "defaultShell", "value": "/bin/bash" })
set_config_value({ "key": "allowedDirectories", "value": ["/Users/username/projects"] })

Configuration is saved in config.json and persists across restarts.

Best Practices

Use a dedicated chat for configuration changes.
Avoid empty allowedDirectories (this grants full filesystem access).
Specify exact directories instead of broad paths (like /).
Verify changes with get_config({}).

Using Different Shells

Specify shell for command execution:

// Default shell
execute_command({ "command": "echo $SHELL" })

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

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

Debugging

To debug the server, install in debug mode:

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

Or if installed locally:

npm run setup:debug

Debugging features:

Enables Node.js inspector protocol (--inspect-brk=9229) and pauses execution until debugger attachment.
Connect with Chrome via chrome://inspect or VS Code "Attach to Node Process".
Debug server appears as "desktop-commander-debug" in Claude's MCP server list.

Model Context Protocol Integration

Extends MCP Filesystem Server by adding:

Local server support in Claude Desktop
Full system command execution
Process management
File operations
Code editing with search/replace blocks

Completed Improvements (selected)

Better configurations for allowed paths, commands, and shells
Windows and Linux environment fixes
Added URL support for reading files
Enhanced code search with context-aware results

Work in Progress and TODOs

WSL support
SSH remote command execution
Better file type support (e.g., CSV, PDF)
Terminal sandboxing for better security
File reading modes (e.g., HTML as markdown or plain text)

Website

Visit our official website for updates and documentation:
https://desktopcommander.app/

Media

Community

Join our Discord server to get help, share feedback, and connect with users:
https://discord.gg/kQ27sNnZr7

Testimonials

"It's a life saver! I paid Claude + Cursor and this solves the problem ultimately. With this MCP + Internet search, it writes code with latest updates. It's so good when Cursor doesn't work or requests are used up."
— YouTube testimonial

"I updated an old Flutter app using Claude MCP in a couple of hours. Amazing tool that allows surgical edits, like a human developer."

"This Claude MCP allowed me to code as much as I want without worrying about token cost."

"Claude Desktop Commander replaced multiple IDE assistants and improved my workflow significantly."

Contributing

If you find this project useful, please ⭐ star it on GitHub!

Ways to contribute:

Report bugs or submit feature requests via GitHub Issues
Fork, develop, and submit pull requests
Participate in discussions on GitHub Discussions
Support the project: Buy Me A Coffee

Frequently Asked Questions

What is DesktopCommanderMCP?
An MCP tool that lets Claude Desktop access your filesystem and terminal for coding, automation, and codebase exploration.

How does this differ from Cursor/Windsurf?
Claude Desktop Commander works across your entire OS, reading full files and enabling changes in bulk with surgical precision.

Do I need to pay for API credits?
No. It works with Claude Desktop’s standard Pro subscription ($20/month).

Does it update automatically?
Yes, when installed via npx or Smithery, it updates on Claude restart.

Common use cases:

Understanding complex codebases
Automating system tasks
Making precise code changes

Need help?
Join Discord: https://discord.gg/kQ27sNnZr7
Check GitHub issues or the website FAQ.

Data Collection

Desktop Commander collects anonymous usage data for improvement, including:

OS info
Node.js and npm versions
Installation method and shell environment
Error messages during setup

No personal data is collected. An opt-out option will be added soon. Blocking google-analytics.com will prevent data collection.

License

MIT

ClaudeDesktopCommander

📌Overview

Desktop Commander MCP

Search, update, manage files and run terminal commands with AI

Table of Contents

Features

Installation

Option 1: Install through npx

Option 2: Bash script installer (macOS)

Option 3: Installing via Smithery

Option 4: Add to claude_desktop_config manually

Option 5: Checkout locally

Updating Desktop Commander

Usage

Tool Usage Examples

URL Support

Handling Long-Running Commands

Configuration Management

Important Security Warnings

Using Configuration Tools

Best Practices

Using Different Shells

Debugging

Model Context Protocol Integration

Completed Improvements (selected)

Work in Progress and TODOs

Website

Media

Article

Video

Publication at AnalyticsIndiaMag

Community

Testimonials

Contributing

Frequently Asked Questions

Data Collection

License