This MCP server provides terminal commands alongside file operations and process management. Its purpose is described as “Search, update, manage files and run terminal commands with AI,” and it is associated with the @wonderwhy-er/desktop-commander package. The catalog record includes topics related to MCP, terminal automation, and AI-assisted coding workflows.
🛠️ Key Features
Terminal commands
File operations (search and update)
Process management
AI-enabled workflow for running commands
🚀 Use Cases
Search and update files during development tasks
Manage files as part of terminal automation
Run terminal commands that depend on current project state
Handle processes during automated or assisted coding sessions
⚡ Developer Benefits
Built for MCP integration (mcp topic present)
Supports terminal automation use cases (terminal-automation, terminal-ai)
Positioned for code-analysis and code-generation workflows (code-analysis, code-generation)
⚠️ Limitations
No further operational details are provided beyond command execution, file operations, and process management.
Work with code and text, run processes, and automate tasks, going far beyond other AI editors - while using host client subscriptions instead of API token costs.
All of your AI development tools in one place.
Desktop Commander puts all dev tools in one chat.
Execute long-running terminal commands on your computer and manage processes through Model Context Protocol (MCP). Built on top of MCP Filesystem Server to provide additional search and replace file editing capabilities.
Features
Remote AI Control - Use Desktop Commander from ChatGPT, Claude web, and other AI services via Remote MCP
File Preview UI - Visual file previews in Claude Desktop with rendered markdown, inline images, expandable content, built-in markdown editor, and quick "Open in folder" access
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):
--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
Option 2: Using bash script installer (macOS) ⭐ Auto-Updates (Installs Node.js if needed)
✅ 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
Option 6: Docker Installation 🐳 ⭐ Auto-Updates (No Node.js Required)
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.
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.
Roo Code
Add to your Roo Code MCP configuration file. See Roo Code MCP docs for more info.
Claude Code
sh
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.
Trae
Use the "Add manually" feature and paste the JSON configuration above. See Trae MCP docs for more info.
Kiro
Navigate to Kiro > MCP Servers, click + Add, and paste the JSON configuration above. See Kiro MCP docs for more info.
Codex (OpenAI)
Codex uses TOML configuration. Run this command to add Desktop Commander:
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.
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.
✅ The Remote Device only accepts commands while it is running
✅ Commands execute locally under your user permissions
✅ Secure OAuth authentication and encrypted communication channel
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.
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
Usage
The server provides a comprehensive set of tools organized into several categories:
Available Tools
Category
Tool
Description
Configuration
get_config
Get the complete server configuration as JSON (includes blockedCommands, defaultShell, allowedDirectories, fileReadLineLimit, fileWriteLineLimit, telemetryEnabled)
set_config_value
Set a specific configuration value by key. Available settings: • blockedCommands: Array of shell commands that cannot be executed • defaultShell: Shell to use for commands (e.g., bash, zsh, powershell) • allowedDirectories: Array of filesystem paths the server can access for file operations (⚠️ terminal commands can still access files outside these directories) • fileReadLineLimit: Maximum lines to read at once (default: 1000) • fileWriteLineLimit: Maximum lines to write at once (default: 50) • telemetryEnabled: Enable/disable telemetry (boolean)
Terminal
start_process
Start programs with smart detection of when they're ready for input
interact_with_process
Send commands to running programs and get responses
read_process_output
Read output from running processes
force_terminate
Force terminate a running terminal session
list_sessions
List all active terminal sessions
list_processes
List all running processes with detailed information
kill_process
Terminate a running process by PID
Filesystem
read_file
Read contents from local filesystem, URLs, Excel files (.xlsx, .xls, .xlsm), and PDFs with line/page-based pagination
read_multiple_files
Read multiple files simultaneously
write_file
Write file contents with options for rewrite or append mode. Supports Excel files (JSON 2D array format). For PDFs, use write_pdf
write_pdf
Create new PDF files from markdown or modify existing PDFs (insert/delete pages). Supports HTML/CSS styling and SVG graphics
create_directory
Create a new directory or ensure it exists
list_directory
Get detailed recursive listing of files and directories (supports depth parameter, default depth=2)
move_file
Move or rename files and directories
start_search
Start streaming search for files by name or content patterns (searches text files and Excel content)
get_more_search_results
Get paginated results from active search with offset support
stop_search
Stop an active search gracefully
list_searches
List all active search sessions
get_file_info
Retrieve detailed metadata about a file or directory (includes sheet info for Excel files)
Text Editing
edit_block
Apply targeted text replacements for text files, or range-based cell updates for Excel files
Analytics
get_usage_stats
Get usage statistics for your own insight
get_recent_tool_calls
Get recent tool call history with arguments and outputs for debugging and context recovery
give_feedback_to_desktop_commander
Open feedback form in browser to provide feedback to Desktop Commander Team
Quick Examples
Data Analysis:
code
"Analyze sales.csv and show top customers" → Claude runs Python code in memory
Remote Access:
code
"SSH to my server and check disk space" → Claude maintains SSH session
Development:
code
"Start Node.js and test this API" → Claude runs interactive Node session
Tool Usage Examples
Search/Replace Block Format:
code
filepath.ext
<<<<<<< SEARCH
content to find
=======
new content
>>>>>>> REPLACE
The edit_block tool includes several enhancements for better reliability:
Improved Prompting: Tool descriptions now emphasize making multiple small, focused edits rather than one large change
Fuzzy Search Fallback: When exact matches fail, it performs fuzzy search and provides detailed feedback
Character-level Diffs: Shows exactly what's different using {-removed-}{+added+} format
Multiple Occurrence Support: Can replace multiple instances with expected_replacements parameter
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
Install Docker for Windows/Mac
Download and install Docker Desktop from docker.com
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
Why exact matches fail: Common issues like whitespace differences, line endings, or character encoding
Performance patterns: How search complexity affects execution time
File type issues: Which file extensions commonly have matching problems
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.
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.
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
Known security limitations: Directory restrictions and command blocking can be bypassed through various methods including symlinks, command substitution, and absolute paths or code execution
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.
The allowedDirectories setting currently only restricts filesystem operations, not terminal commands. Terminal commands can still access files outside allowed directories.
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:
javascript
// Get the entire configget_config({})
// Set a specific config valueset_config_value({ "key": "defaultShell", "value": "/bin/zsh" })
// Set multiple config values using separate callsset_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:
javascript
// You can set it to thousands if you wantset_config_value({ "key": "fileWriteLineLimit", "value": 1000 })
// Or keep it smaller to force more efficient behaviorset_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
Create a dedicated chat for configuration changes: Make all your config changes in one chat, then start a new chat for your actual work.
Be careful with empty allowedDirectories: Setting this to an empty array ([]) grants access to your entire filesystem for file operations.
Use specific paths: Instead of using broad paths like /, specify exact directories you want to access.
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:
bash
# 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:
javascript
// Using default shell (bash or system default)execute_command({ "command": "echo $SHELL" })
// Using zsh specificallyexecute_command({ "command": "echo $SHELL", "shell": "/bin/zsh" })
// Using bash specificallyexecute_command({ "command": "echo $SHELL", "shell": "/bin/bash" })
This allows you to use shell-specific features or maintain consistent environments across commands.
execute_command returns after timeout with initial output
Command continues in background
Use read_output with PID to get new output
Use force_terminate to stop if needed
Debugging
If you need to debug the server, you can install it in debug mode:
bash
# Using npx
npx @wonderwhy-er/desktop-commander@latest setup --debug
# Or if installed locally
npm run setup:debug
This will:
Configure Claude to use a separate "desktop-commander" server
Enable Node.js inspector protocol with --inspect-brk=9229 flag
Pause execution at the start until a debugger connects
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:
Desktop Commander MCP is free and open source, but needs your support to thrive!
Our philosophy is simple: we don't want you to pay for it if you're not successful. But if Desktop Commander contributes to your success, please consider contributing to ours.
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:
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.
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.
This Developer Ditched Windsurf, Cursor Using Claude with MCPs
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://medium.com/@pharmx/you-sir-are-my-hero-62cff5836a3e