Claudedesktopcommander

Desktop Commander MCP is a service that enables the Claude desktop application to execute terminal commands on the user's computer and manage processes through the Model Context Protocol (MCP). It provides terminal command execution, process management, file system operations, and code editing functions, supporting long-running commands and differential file editing.

Developer tools Operating system automation #Terminal control #Process management #File editing #MCP protocol .TypeScript

rating : 2.5 points

downloads : 9.6K

update time : 2025-07-31

Open Site

What is Desktop Commander MCP?

Desktop Commander MCP is a tool that allows the Claude AI assistant to directly interact with your computer. It enables Claude to execute terminal commands, manage processes, operate the file system, and perform precise code editing.

How to use Desktop Commander MCP?

After installation, you can directly execute commands, edit files, or manage system processes in the Claude desktop application through natural language instructions.

Applicable scenarios

Suitable for scenarios where developers want to use natural language to control the computer to complete coding, file operations, and system management tasks.

Main features

Terminal command execution

Execute various terminal commands and obtain real-time output

Process management

View and terminate system processes

File operations

Complete file system operations such as reading and writing files, creating directories, and moving files

Code editing

Supports two editing modes: precise search and replacement and complete file rewriting

Advantages

Complete development and system management tasks without switching tools

Support long-running commands and background processes

Provide precise code editing capabilities

Seamlessly integrate with the Claude desktop application

Limitations

Support for the Windows environment is still being improved

Requires certain technical knowledge for configuration and use

Pay attention to security when executing commands

How to use

Installation

Install Desktop Commander MCP via npm

Restart Claude

Restart the Claude desktop application after installation is complete

Start using

Directly enter commands or editing requests in Claude

Usage examples

Update project dependencies

Let Claude check and update the npm dependencies of the project

Modify specific lines in the code

Precisely modify specific parts of the code file

Frequently Asked Questions

What should I do if Claude cannot recognize commands after installation?

How to ensure the security of command execution?

Related resources

Video tutorial

Demonstration of using Desktop Commander

GitHub repository

Project source code and issue tracking

Discord community

Get help and share feedback

🚀 Desktop Commander MCP

Desktop Commander MCP is a server that enables the Claude desktop app to execute long - running terminal commands on your computer and manage processes. It also offers file editing capabilities based on the Model Context Protocol (MCP).

🚀 Quick Start

This is a server that allows the Claude desktop app to execute long - running terminal commands on your computer and manage processes through the 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: Run terminal commands and get output streamed in real - time.
Command timeout and background execution support: Set timeouts for commands and let them run in the background.
Process management: List and kill processes as needed.
Session management for long - running commands: Keep track of long - running command sessions.
Full filesystem operations:
- Read and write files.
- Create and list directories.
- Move files and directories.
- Search files using patterns.
- Get file metadata.
Code editing capabilities:
- Perform surgical text replacements for small changes.
- Do full file rewrites for major changes.
- Support multiple files.
- Use pattern - based replacements.

📦 Installation

First, make sure you have downloaded and installed the Claude Desktop app and have npm installed.

Option 1: Installing via Smithery

To install Desktop Commander for Claude Desktop automatically via Smithery:

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

Option 2: Install through npx

Just run this in the terminal:

npx @wonderwhy-er/desktop-commander setup

Restart Claude if it is running.

Option 3: Add to claude_desktop_config by hand

Add this entry to your claude_desktop_config.json (on Mac, found at ~/Library/Application\ Support/Claude/claude_desktop_config.json):

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

Restart Claude if it is running.

Option 4: Checkout locally

Clone and build:

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

Restart Claude if it is running.

The setup command will:

Install dependencies.
Build the server.
Configure Claude's desktop app.
Add MCP servers to Claude's config if needed.

💻 Usage Examples

Basic Usage

The server provides these tool categories:

Terminal Tools

execute_command: Run commands with configurable timeout.
read_output: Get output from long - running commands.
force_terminate: Stop running command sessions.
list_sessions: View active command sessions.
list_processes: View system processes.
kill_process: Terminate processes by PID.
block_command/unblock_command: Manage command blacklist.

Filesystem Tools

read_file/write_file: File operations.
create_directory/list_directory: Directory management.
move_file: Move/rename files.
search_files: Pattern - based file search.
get_file_info: File metadata.

Edit Tools

edit_block: Apply surgical text replacements (best for changes <20% of file size).
write_file: Complete file rewrites (best for large changes >20% or when edit_block fails).

Search/Replace Block Format:

filepath.ext
<<<<<<< SEARCH
existing code to replace
=======
new code to insert
>>>>>>> REPLACE

Example:

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

🔧 Technical Details

Handling Long - Running Commands

For commands that may take a while:

execute_command returns after timeout with initial output.
The command continues in the background.
Use read_output with PID to get new output.
Use force_terminate to stop if needed.

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.

It was created as part of exploring Claude MCPs: https://youtube.com/live/TlbjFDbl5Us

Work in Progress and TODOs

The following features are currently being developed or planned:

Better code search (in progress) - Enhanced code exploration with context - aware results.
Better configurations (in progress) - Improved settings for allowed paths, commands and shell environment.
Windows environment fixes (in progress) - Resolving issues specific to Windows platforms.
Linux improvements (in progress) - Enhancing compatibility with various Linux distributions.
Support for WSL - Windows Subsystem for Linux integration.
Support for SSH - Remote server command execution.
Installation troubleshooting guide - Comprehensive help for setup issues.

📚 Documentation

Media links

Learn more about this project through these resources:

Article: Claude with MCPs replaced Cursor & Windsurf. How did that happen? - A detailed exploration of how Claude with Model Context Protocol capabilities is changing developer workflows.
Video: Claude Desktop Commander Video Tutorial - Watch how to set up and use the Commander effectively.
Community: Join our Discord server to get help, share feedback, and connect with other users.

Testimonials

https://www.youtube.com/watch?v=ly3bed99Dy8&lc=UgyyBt6_ShdDX_rIOad4AaABAg
https://www.youtube.com/watch?v=ly3bed99Dy8&lc=UgztdHvDMqTb9jiqnf54AaABAg
https://www.youtube.com/watch?v=ly3bed99Dy8&lc=UgyQFTmYLJ4VBwIlmql4AaABAg
[ https://www.youtube.com/watch?v=ly3bed99Dy8&lc=Ugy4 - exy166_Ma7TH - h4AaABAg](https://www.youtube.com/watch?v=ly3bed99Dy8&lc=Ugy4 - exy166_Ma7TH - h4AaABAg)
[ https://medium.com/@pharmx/you - sir - are - my - hero - 62cff5836a3e](https://medium.com/@pharmx/you - sir - are - my - hero - 62cff5836a3e)

🤝 Contributing

If you find this project useful, please consider giving it a ⭐ star on GitHub! This helps others discover the project and encourages further development.

We welcome contributions from the community! Whether you've found a bug, have a feature request, or want to contribute code, here's how you can help:

Found a bug? Open an issue at github.com/wonderwhy-er/ClaudeComputerCommander/issues.
Have a feature idea? Submit a feature request in the issues section.
Want to contribute code? Fork the repository, create a branch, and submit a pull request.
Questions or discussions? Start a discussion in the GitHub Discussions tab.

All contributions, big or small, are greatly appreciated!

If you find this tool valuable for your workflow, please consider supporting the project.

📄 License

MIT

execute_command

Execute a terminal command within the timeout period. If the command does not complete within the timeout period, it will continue to run in the background.

Parameters

: *

Description

Parameters

: *

Description

read_output

Read new output from a running terminal session.

Parameters

: *

Description

force_terminate

Forcefully terminate a running terminal session.

Parameters

: *

Description

list_sessions

List all active terminal sessions.

list_processes

List all running processes. Return process information including PID, command name, CPU usage, and memory usage.

kill_process

Terminate a running process by PID. Use with caution as this will forcefully terminate the specified process.

Parameters

: *

Description

block_command

Add a command to the blacklist. Once blocked, the command cannot be executed until it is unblocked.

Parameters

: *

Description

unblock_command

Remove a command from the blacklist. Once unblocked, the command can be executed normally.

Parameters

: *

Description

list_blocked_commands

List all currently blocked commands.

read_file

Read the complete content of a file from the file system. Handle various text encodings and provide detailed error messages when the file cannot be read. Only applicable to allowed directories.

Parameters

: *

Description

read_multiple_files

Read the content of multiple files simultaneously. The content of each file is returned along with its path. The failure to read a single file does not stop the entire operation. Only applicable to allowed directories.

Parameters

: *

Description

write_file

Completely replace the file content. Most suitable for large changes (>20% of the file size) or when edit_block fails. Use with caution as it will overwrite the existing file. Only applicable to allowed directories.

Parameters

: *

Description

Parameters

: *

Description

create_directory

Create a new directory or ensure that the directory exists. Can create multiple nested directories in a single operation. Only applicable to allowed directories.

Parameters

: *

Description

list_directory

Get a detailed list of all files and directories in the specified path. The results are distinguished between files and directories by the [FILE] and [DIR] prefixes. Only applicable to allowed directories.

Parameters

: *

Description

move_file

Move or rename files and directories. Can move files between directories and rename them in a single operation. Both the source and destination must be within the allowed directories.

Parameters

: *

Description

Parameters

: *

Description

search_files

Recursively search for files and directories that match the pattern. Search all subdirectories from the starting path. Only search within the allowed directories.

Parameters

: *

Description

Parameters

: *

Description

get_file_info

Retrieve detailed metadata of a file or directory, including size, creation time, last modification time, permissions, and type. Only applicable to allowed directories.

Parameters

: *

Description

list_allowed_directories

Return a list of directories that this server allows access to.

edit_block

Perform precise text replacement on a file. Most suitable for small changes (<20% of the file size). Can use multiple blocks for separate changes. The changes will be verified after application. Format: file path, then <<<<<<< SEARCH, content to find, =======, new content, >>>>>>> REPLACE.

Parameters

: *

Description