Claude Desktop Commander MCP
Desktop Commander MCP turns an AI client into a local dev/automation agent — full filesystem access, terminal and process control, surgical code editing, and rich document handling.
Read/write files: text, images, URLs, Excel (.xlsx/.xls/.xlsm as JSON 2D arrays), PDF text extraction, DOCX (outline or raw XML), with line/page/row pagination and negative offsets for tail-style reads
Create & edit PDFs: build from markdown with HTML/CSS/SVG styling, insert or delete pages, force page breaks
Filesystem management: recursive directory listing with depth control and overflow protection, create directories, move/rename files and folders, read metadata (size, permissions, line counts, sheets)
Search: streaming file-name or content search with regex/literal matching, file-type filters, case insensitivity, and paginated results
Code editing: targeted
edit_blockfind/replace (single or multiple occurrences), Excel range updates, DOCX XML editing, with fuzzy-match diff feedback on failuresTerminal & processes: start shell commands and interactive REPLs (Python, Node, R), send input, read paginated output, detect prompts/completion, list sessions, force-terminate
System process control: list running processes with CPU/memory, kill by PID
Configuration: get/set blockedCommands, defaultShell, allowedDirectories, fileReadLineLimit, fileWriteLineLimit, telemetryEnabled at runtime
Analytics & history: usage statistics, recent tool-call history with arguments/outputs, feedback form launcher
Note: this instance is running in a Linux Docker container with no mounted volumes, so files created outside mounts won't persist.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Claude Desktop Commander MCP show me the last 10 lines of my application.log file"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Desktop Commander MCP
Search, update, manage files and run terminal commands with AI
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.
Table of Contents
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.
Related MCP server: Desktop Commander MCP
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_callsSize-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
How to install
For ChatGPT, Claude web, and other remote clients, see the Remote device launchers. They install Node.js when missing and run Desktop Commander Remote on macOS, Linux, or Windows.
Install in Claude Desktop
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 setupFor debugging mode (allows Node.js inspector connection):
npx @wonderwhy-er/desktop-commander@latest setup --debugCommand 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 | bashThis 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
Visit: https://smithery.ai/server/@wonderwhy-er/desktop-commander
Login to Smithery if you haven't already
Select your client (Claude Desktop) on the right side
Install with the provided key that appears after selecting your client
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.jsonOn Windows:
%APPDATA%\Claude\claude_desktop_config.jsonOn 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 setupRestart 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) --resetWindows 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")) -HelpTroubleshooting: 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:
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@latestRemove --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@latestOr 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@latestOr 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 remoteOn first run, complete browser authentication, then connect your AI at mcp.desktopcommander.app.
Stop the local device temporarily with
Ctrl+CSee available CLI options with
npx @wonderwhy-er/desktop-commander@latest remote --helpSee 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
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 removeThis 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
Locate your Claude Desktop config file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonLinux:
~/.config/Claude/claude_desktop_config.json
Edit the config file:
Open the file in a text editor
Find and remove the
"desktop-commander"entry from the"mcpServers"sectionSave 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
Usage
The server provides a comprehensive set of tools organized into several categories:
Available Tools
Category | Tool | Description |
Configuration |
| Get the complete server configuration as JSON (includes blockedCommands, defaultShell, allowedDirectories, fileReadLineLimit, fileWriteLineLimit, telemetryEnabled) |
| Set a specific configuration value by key. Available settings: • | |
Terminal |
| Start programs with smart detection of when they're ready for input |
| Send commands to running programs and get responses | |
| Read output from running processes | |
| Force terminate a running terminal session | |
| List all active terminal sessions | |
| List all running processes with detailed information | |
| Terminate a running process by PID | |
Filesystem |
| Read contents from local filesystem, URLs, Excel files (.xlsx, .xls, .xlsm), and PDFs with line/page-based pagination |
| Read multiple files simultaneously | |
| Write file contents with options for rewrite or append mode. Supports Excel files (JSON 2D array format). For PDFs, use | |
| Create new PDF files from markdown or modify existing PDFs (insert/delete pages). Supports HTML/CSS styling and SVG graphics | |
| Create a new directory or ensure it exists | |
| Get detailed recursive listing of files and directories (supports depth parameter, default depth=2) | |
| Move or rename files and directories | |
| Start streaming search for files by name or content patterns (searches text files and Excel content) | |
| Get paginated results from active search with offset support | |
| Stop an active search gracefully | |
| List all active search sessions | |
| Retrieve detailed metadata about a file or directory (includes sheet info for Excel files) | |
Text Editing |
| Apply targeted text replacements for text files, or range-based cell updates for Excel files |
Analytics |
| Get usage statistics for your own insight |
| Get recent tool call history with arguments and outputs for debugging and context recovery | |
| Open feedback form in browser to provide feedback to Desktop Commander Team |
Quick Examples
Data Analysis:
"Analyze sales.csv and show top customers" → Claude runs Python code in memoryRemote Access:
"SSH to my server and check disk space" → Claude maintains SSH sessionDevelopment:
"Start Node.js and test this API" → Claude runs interactive Node sessionTool Usage Examples
Search/Replace Block Format:
filepath.ext
<<<<<<< SEARCH
content to find
=======
new content
>>>>>>> REPLACEExample:
src/main.js
<<<<<<< SEARCH
console.log("old message");
=======
console.log("new message");
>>>>>>> REPLACEEnhanced Edit Block Features
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+}formatMultiple Occurrence Support: Can replace multiple instances with
expected_replacementsparameterComprehensive 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
Get Desktop Commander Docker Configuration
Visit: https://hub.docker.com/mcp/server/desktop-commander/manual
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

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
URL Support
read_filecan now fetch content from both local files and URLsExample:
read_filewithisUrl: trueparameter to read from web resourcesHandles 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
Desktop Commander includes a rich file preview widget in Claude Desktop that renders files visually as AI works with them.
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 viewing a .md file in Claude Desktop, you can edit it directly inside the preview panel — no need to open a separate app.
How to use:
Ask Claude to read or create a markdown file
Expand the file preview to fullscreen using the ⤢ Expand button
The editor activates automatically in fullscreen mode
Edit your content with a live preview toggle, copy, undo, and save controls
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
When Claude runs list_directory, the result opens as an interactive file tree inside the preview panel — not just raw text output.
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 allbutton instead of overwhelming the viewOpen 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:clearFor detailed documentation on these scripts, see scripts/README.md.
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.logWindows:
%USERPROFILE%\.claude-server-commander-logs\fuzzy-search.log
What You'll Learn
The fuzzy search logs help you understand:
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.
Locations:
macOS/Linux:
~/.claude-server-commander/claude_tool_call.logWindows:
%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_callsandtrack_ui_eventare excluded from this JSONL history.
Locations:
macOS/Linux:
~/.claude-server-commander/tool-history.jsonlWindows:
%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
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
allowedDirectoriessetting 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:
// 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
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:
# 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-onboardingflagAfter 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.
execute_commandreturns after timeout with initial outputCommand continues in background
Use
read_outputwith PID to get new outputUse
force_terminateto 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:debugThis will:
Configure Claude to use a separate "desktop-commander" server
Enable Node.js inspector protocol with
--inspect-brk=9229flagPause execution at the start until a debugger connects
Enable additional debugging environment variables
To connect a debugger:
In Chrome, visit
chrome://inspectand look for the Node.js instanceIn 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-brkflag)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
Support Desktop Commander
❤️ Supporters Hall of Fame
Generous supporters are featured here. Thank you for helping make this project possible!
Website
Visit our official website at https://desktopcommander.app/ for the latest information, documentation, and updates.
Media
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.
Publication at AnalyticsIndiaMag
This Developer Ditched Windsurf, Cursor Using Claude with MCPs
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://medium.com/@pharmx/you-sir-are-my-hero-62cff5836a3e
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/DesktopCommanderMCP/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.
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.
Verifications
License
MIT
Available Tools
25 toolscreate_directoryA
Create a new directory or ensure a directory exists.
Can create multiple nested directories in one operation.
Only works within allowed directories.
Absolute paths are the most reliable because they do not depend on the current working directory. Paths are automatically normalized regardless of slash direction. Relative paths depend on the current working directory, and tilde paths (~/...) may not resolve in every context. Absolute paths are generally the most reliable.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.Inputs: path (required).
edit_blockADestructive
Apply surgical edits to files.
Small, focused edits are easier to verify than large multi-purpose replacements.
old_string can include enough surrounding context to uniquely identify the intended text.
FORMAT HANDLING (by extension):
EXCEL FILES (.xlsx, .xls, .xlsm) - Range Update mode:
Takes:
- file_path: Path to the Excel file
- range uses FROM:TO format - "SheetName!A1:C10" or "SheetName!C1:C1"
- content: 2D array, e.g., [["H1","H2"],["R1","R2"]]
TEXT FILES - Find/Replace mode:
Takes:
- file_path: Path to the file to edit
- old_string: Text to replace
- new_string: Replacement text
- expected_replacements: Optional number of replacements (default: 1)
DOCX FILES (.docx) - XML Find/Replace mode:
Takes same parameters as text files (old_string, new_string, expected_replacements).
Operates on the pretty-printed XML inside the DOCX — the same XML you see from
read_file with offset/length. Copy XML fragments from read output as old_string.
After editing, the XML is repacked into a valid DOCX.
Also searches headers/footers if not found in document body.
Examples:
- Replace text: old_string="<w:t>Old Text</w:t>" new_string="<w:t>New Text</w:t>"
- Change style: old_string='<w:pStyle w:val="Normal"/>' new_string='<w:pStyle w:val="Heading1"/>'
- Add content: include surrounding XML context in old_string, add new elements in new_string
By default, replaces only ONE occurrence of the search text.
To replace multiple occurrences, provide expected_replacements with
the exact number of matches expected.
UNIQUENESS REQUIREMENT: When expected_replacements=1 (default), include the minimal
amount of context necessary (typically 1-3 lines) before and after the change point,
with exact whitespace and indentation.
When editing multiple sections, make separate edit_block calls for each distinct change
rather than one large replacement.
When a close but non-exact match is found, a character-level diff is shown in the format:
common_prefix{-removed-}{+added+}common_suffix to help you identify what's different.
Similar to write_file, there is a configurable line limit (fileWriteLineLimit) that warns
if the edited file exceeds this limit. If this happens, consider breaking your edits into
smaller, more focused changes.
Absolute paths are the most reliable because they do not depend on the current working directory. Paths are automatically normalized regardless of slash direction. Relative paths depend on the current working directory, and tilde paths (~/...) may not resolve in every context. Absolute paths are generally the most reliable.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.Inputs: file_path (required), range, origin, content, +4 more.
force_terminateCDestructive
Force terminate a running terminal session.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.Inputs: pid (required).
get_configBRead-only
Get the complete server configuration as JSON. Config includes fields for:
- blockedCommands (array of blocked shell commands)
- defaultShell (shell to use for commands)
- allowedDirectories (paths the server can access)
- fileReadLineLimit (max lines for read_file, default 1000)
- fileWriteLineLimit (max lines per write_file call, default 50)
- telemetryEnabled (boolean for telemetry opt-in/out)
- currentClient (information about the currently connected MCP client)
- clientHistory (history of all clients that have connected)
- version (version of the DesktopCommander)
- systemInfo (operating system and environment details)
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.Inputs: origin.
get_file_infoARead-only
Retrieve detailed metadata about a file or directory including:
- size
- creation time
- last modified time
- permissions
- type
- lineCount (for text files)
- lastLine (zero-indexed number of last line, for text files)
- appendPosition (line number for appending, for text files)
- sheets (for Excel files - array of {name, rowCount, colCount})
Only works within allowed directories.
Absolute paths are the most reliable because they do not depend on the current working directory. Paths are automatically normalized regardless of slash direction. Relative paths depend on the current working directory, and tilde paths (~/...) may not resolve in every context. Absolute paths are generally the most reliable.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.Inputs: path (required).
get_more_search_resultsARead-only
Get more results from an active search with offset-based pagination.
Supports partial result reading with:
- 'offset' (start result index, default: 0)
* Positive: Start from result N (0-based indexing)
* Negative: Read last N results from end (tail behavior)
- 'length' (max results to read, default: 100)
* Used with positive offsets for range reading
* Ignored when offset is negative (reads all requested tail results)
Examples:
- offset: 0, length: 100 → First 100 results
- offset: 200, length: 50 → Results 200-249
- offset: -20 → Last 20 results
- offset: -5, length: 10 → Last 5 results (length ignored)
Returns only results in the specified range, along with search status.
Works like read_process_output - call this repeatedly to get progressive
results from a search started with start_search.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.Inputs: sessionId (required), length, offset.
get_recent_tool_callsARead-only
Get recent local tool call history with arguments and outputs.
Returns a chronological list of recent calls loaded from the local history file.
Useful for:
- Onboarding new chats about work already done
- Recovering context after chat history loss
- Debugging tool call sequences
Note: Does not track its own calls or track_ui_event.
History is persisted locally in tool-history.jsonl, keeps up to the last 1000
calls in memory, and trims older on-disk history. Stored outputs over 4 KiB
are replaced with an omission marker.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.Inputs: since, toolName, maxResults.
get_usage_statsARead-only
Get usage statistics for debugging and analysis.
Returns summary of tool usage, success/failure rates, and performance metrics.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.Inputs: no named parameters.
give_feedback_to_desktop_commanderA
Open feedback form in browser to provide feedback about Desktop Commander.
The form itself collects survey answers; this tool does not accept survey responses or
pre-fill them. It automatically includes basic usage metadata:
- tool_call_count: Number of commands made
- days_using: Number of days Desktop Commander has been used
- platform: Operating system (Mac/Windows/Linux)
- client_id: Analytics identifier
No input parameters are required.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.Inputs: no named parameters.
interact_with_processADestructive
Send input to an existing terminal or REPL process and return newly available output.
Useful for interactive shells, Python/Node/R/Julia REPLs, database consoles,
and long-running commands started with start_process().
Examples:
- Interactive Python REPL sessions can be started with `python3 -i`.
- Existing interactive sessions accept additional input such as imports or analysis commands.
- Interactive sessions can return newly available output while they remain active.
SMART DETECTION:
- Automatically waits for a recognized prompt when requested
- Detects errors and completion states
- Early exit prevents unnecessary waiting
- Cleans common REPL prompt text from returned output
PARAMETERS:
- pid: Process ID returned by start_process
- input: Text or command to send to the process
- timeout_ms: Maximum wait time (default: 8000ms)
- wait_for_prompt: Whether to wait for a prompt before returning (default: true)
- verbose_timing: Include detailed timing telemetry (default: false)
Returns execution result with status indicators.
PERFORMANCE DEBUGGING (verbose_timing parameter):
When enabled, detailed timing includes:
- Exit reason
- Total duration and time to first output
- Timeline of output events
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.Inputs: pid (required), input (required), timeout_ms, verbose_timing, +1 more.
kill_processADestructive
Terminate a running process by PID.
For a PID that start_process returned, it ends the whole command: the shell and every process the command started, as force_terminate does. Any other PID ends that process only. Sessions started with node:local have a negative PID; stop them with force_terminate.
Use with caution as this will forcefully terminate the specified process.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.Inputs: pid (required).
list_directoryARead-only
Get a detailed listing of all files and directories in a specified path.
Returns a structured directory listing without starting a shell command.
Results distinguish between files and directories with [FILE] and [DIR] prefixes.
Supports recursive listing with the 'depth' parameter (default: 2):
- depth=1: Only direct contents of the directory
- depth=2: Contents plus one level of subdirectories
- depth=3+: Multiple levels deep
CONTEXT OVERFLOW PROTECTION:
- Top-level directory shows ALL items
- Nested directories are limited to 100 items maximum per directory
- When a nested directory has more than 100 items, you'll see a warning like:
[WARNING] node_modules: 500 items hidden (showing first 100 of 600 total)
- This prevents overwhelming the context with large directories like node_modules
Results show full relative paths from the root directory being listed.
Example output with depth=2:
[DIR] src
[FILE] src/index.ts
[DIR] src/tools
[FILE] src/tools/filesystem.ts
If a directory cannot be accessed, it will show [DENIED] instead.
If a path does not exist, it will show [NOT_FOUND] instead.
Only works within allowed directories.
Absolute paths are the most reliable because they do not depend on the current working directory. Paths are automatically normalized regardless of slash direction. Relative paths depend on the current working directory, and tilde paths (~/...) may not resolve in every context. Absolute paths are generally the most reliable.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.Inputs: path (required), depth, origin.
list_processesARead-only
List all running processes.
Returns process information including PID, command name, CPU usage, and memory usage.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.Inputs: no named parameters.
list_searchesARead-only
List all active searches.
Shows search IDs, search types, patterns, status, and runtime.
Similar to list_sessions for terminal processes. Useful for managing
multiple concurrent searches.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.Inputs: no named parameters.
list_sessionsARead-only
List all active terminal sessions.
Shows session status including:
- PID: Process identifier
- Blocked: Whether session is waiting for input
- Runtime: How long the session has been running
DEBUGGING REPLs:
- "Blocked: true" often means REPL is waiting for input
- Use this to verify sessions are running before sending input
- Long runtime with blocked status may indicate stuck process
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.Inputs: no named parameters.
move_fileADestructive
Move or rename files and directories.
Can move files between directories and rename them in a single operation.
Both source and destination must be within allowed directories.
Absolute paths are the most reliable because they do not depend on the current working directory. Paths are automatically normalized regardless of slash direction. Relative paths depend on the current working directory, and tilde paths (~/...) may not resolve in every context. Absolute paths are generally the most reliable.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.Inputs: source (required), destination (required).
read_fileARead-only
Read contents from files and URLs.
Read PDF files and extract content as markdown and images.
Suitable for reading authorized local files directly without starting a shell command.
Supports partial file reading with:
- 'offset' (start line, default: 0)
* Positive: Start from line N (0-based indexing)
* Negative: Read last N lines from end (tail behavior)
- 'length' (max lines to read, default: configurable via 'fileReadLineLimit' setting, initially 1000)
* Used with positive offsets for range reading
* Ignored when offset is negative (reads all requested tail lines)
Examples:
- offset: 0, length: 10 → First 10 lines
- offset: 100, length: 5 → Lines 100-104
- offset: -20 → Last 20 lines
- offset: -5, length: 10 → Last 5 lines (length ignored)
Performance optimizations:
- Large files with negative offsets use reverse reading for efficiency
- Large files with deep positive offsets use byte estimation
- Small files use fast readline streaming
When reading from the file system, only works within allowed directories.
Can fetch content from URLs when isUrl parameter is set to true
(URLs are always read in full regardless of offset/length).
FORMAT HANDLING (by extension):
- Text: Uses offset/length for line-based pagination
- Excel (.xlsx, .xls, .xlsm): Returns JSON 2D array
* sheet: "Sheet1" (name) or "0" (index as string, 0-based)
* range uses FROM:TO format (e.g., "A1:D100", "C1:C1", "B2:B50")
* offset/length work as row pagination (optional fallback)
- Images (PNG, JPEG, GIF, WebP): Base64 encoded viewable content
- PDF: Extracts text content as markdown with page structure
* offset/length work as page pagination (0-based)
* Includes embedded images when available
- DOCX (.docx): Two modes depending on parameters:
* DEFAULT (no offset/length): Returns a text-bearing outline — shows paragraphs with text,
tables with cell content, styles, image refs. Skips shapes/drawings/SVG noise.
Each element shows its body index [0], [1], etc.
* WITH offset/length: Returns raw pretty-printed XML with line pagination.
Use this to drill into specific sections or see the actual XML for editing.
* Raw DOCX XML output is compatible with edit_block's XML find/replace mode using
XML fragments copied from the read output.
* Raw XML mode requires a non-zero offset (offset=1 starts from line 1).
offset=0 returns the outline regardless of length.
* Bulk transformations can be performed programmatically against the DOCX archive
when the task requires changes across many XML text nodes.
Absolute paths are the most reliable because they do not depend on the current working directory. Paths are automatically normalized regardless of slash direction. Relative paths depend on the current working directory, and tilde paths (~/...) may not resolve in every context. Absolute paths are generally the most reliable.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.Inputs: path (required), isUrl, range, sheet, +4 more.
read_multiple_filesARead-only
Read the contents of multiple files simultaneously.
Each file's content is returned with its path as a reference.
Handles text files normally and renders images as viewable content.
Recognized image types: PNG, JPEG, GIF, WebP.
Failed reads for individual files won't stop the entire operation.
Only works within allowed directories.
Absolute paths are the most reliable because they do not depend on the current working directory. Paths are automatically normalized regardless of slash direction. Relative paths depend on the current working directory, and tilde paths (~/...) may not resolve in every context. Absolute paths are generally the most reliable.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.Inputs: paths (required).
read_process_outputARead-only
Read output from a running process with file-like pagination support.
Supports partial output reading with offset and length parameters (like read_file):
- 'offset' (start line, default: 0)
* offset=0: Read NEW output since last read (default, like old behavior)
* Positive: Read from absolute line position
* Negative: Read last N lines from end (tail behavior)
- 'length' (max lines to read, default: configurable via 'fileReadLineLimit' setting)
Examples:
- offset: 0, length: 100 → First 100 NEW lines since last read
- offset: 0 → All new lines (respects config limit)
- offset: 500, length: 50 → Lines 500-549 (absolute position)
- offset: -20 → Last 20 lines (tail)
- offset: -50, length: 10 → Start 50 from end, read 10 lines
OUTPUT PROTECTION:
- Uses same fileReadLineLimit as read_file (default: 1000 lines)
- Returns status like: [Reading 100 lines from line 0 (total: 5000 lines, 4900 remaining)]
- Prevents context overflow from verbose processes
SMART FEATURES:
- For offset=0, waits up to timeout_ms for new output to arrive
- Detects REPL prompts and process completion
- Shows process state (waiting for input, finished, etc.)
DETECTION STATES:
Process waiting for input (ready for interact_with_process)
Process finished execution
Timeout reached (may still be running)
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.Inputs: pid (required), length, offset, timeout_ms, +1 more.
set_config_valueADestructive
Set a specific configuration value by key.
Security note: configuration changes affect later file and command behavior.
Isolating them from untrusted file or command content reduces the chance that external content influences configuration.
Config keys include:
- blockedCommands (array)
- defaultShell (string)
- allowedDirectories (array of paths)
- fileReadLineLimit (number, max lines for read_file)
- fileWriteLineLimit (number, max lines per write_file call)
- telemetryEnabled (boolean)
IMPORTANT: Setting allowedDirectories to an empty array ([]) allows full access
to the entire file system, regardless of the operating system.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.Inputs: key (required), value (required), origin.
start_processBDestructive
Start a terminal process on the authorized device with intelligent state detection.
Suitable for shell commands, interactive REPL sessions, data-processing scripts,
programmatic file analysis, and other long-running terminal work.
Running on Linux (Docker). Default shell: /bin/sh.🐳 DOCKER CONTAINER ENVIRONMENT DETECTED: This Desktop Commander instance is running inside a Docker container.
⚠️ WARNING: No mounted directories detected. Files created outside mounted volumes will be lost when the container stops. Persistent file work requires a mounted directory, available through the Docker installer or a -v mount. Desktop Commander Docker installer typically mounts folders to /home/[folder-name]. Container: 07c9887ef6c7
LINUX-SPECIFIC NOTES:
Package managers vary by distro: apt, yum, dnf, pacman, zypper
Python 3 might be 'python3' command, not 'python'
Standard Unix shell tools available (grep, awk, sed, etc.)
File permissions and ownership important for many operations
Systemd services common on modern distributions
Examples: • start_process("python3 -i") → Start an interactive Python REPL • start_process("node -i") → Start an interactive Node.js REPL • start_process("node:local") → Run stateless Node.js code on the MCP server • start_process("wc -l /path/file.csv") → Run a one-shot shell command Interactive process sessions support follow-up input after they are started. Long-running process sessions expose newly available output while they remain active. Binary files can be processed with appropriate command-line tools or libraries available in the selected process environment. SMART DETECTION: - Detects REPL prompts (>>>, >, $, etc.) - Identifies when a process is waiting for input - Recognizes process completion vs timeout - Early exit prevents unnecessary waiting STATES DETECTED: Process waiting for input (shows prompt) Process finished execution Process running (use read_process_output) PERFORMANCE DEBUGGING (verbose_timing parameter): Set verbose_timing: true to get detailed timing information including: - Exit reason (early_exit_quick_pattern, early_exit_periodic_check, process_exit, timeout) - Total duration and time to first output - Complete timeline of all output events with timestamps - Which detection mechanism triggered early exit Absolute paths are the most reliable because they do not depend on the current working directory. Paths are automatically normalized regardless of slash direction. Relative paths depend on the current working directory, and tilde paths (~/...) may not resolve in every context. Absolute paths are generally the most reliable. This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.
Inputs: command (required), timeout_ms (required), shell, origin, +1 more.
start_searchARead-only
Start a streaming search that can return results progressively.
SEARCH STRATEGY GUIDE:
Choose the right search type based on what the user is looking for:
USE searchType="files" WHEN:
- User asks for specific files: "find package.json", "locate config files"
- Pattern looks like a filename: "*.js", "README.md", "test-*.tsx"
- User wants to find files by name/extension: "all TypeScript files", "Python scripts"
- Looking for configuration/setup files: ".env", "dockerfile", "tsconfig.json"
USE searchType="content" WHEN:
- User asks about code/logic: "authentication logic", "error handling", "API calls"
- Looking for functions/variables: "getUserData function", "useState hook"
- Searching for text/comments: "TODO items", "FIXME comments", "documentation"
- Finding patterns in code: "console.log statements", "import statements"
- User describes functionality: "components that handle login", "files with database queries"
AMBIGUOUS SEARCHES:
Queries that could refer to either filenames or file contents can be covered with two
searches: one with searchType="files" and one with searchType="content".
Example: "find authentication stuff" can pair a filename search for "auth" with a
content search for "authentication".
SEARCH TYPES:
- searchType="files": Find files by name (pattern matches file names)
- searchType="content": Search inside files for text patterns
PATTERN MATCHING MODES:
- Default (literalSearch=false): Patterns are treated as regular expressions
- Literal (literalSearch=true): Patterns are treated as exact strings
literalSearch=true is useful for code patterns with special characters:
- Function calls with parentheses and quotes
- Array access with brackets
- Object methods with dots and parentheses
- File paths with backslashes
- Any pattern containing: . * + ? ^ $ { } [ ] | \ ( )
IMPORTANT PARAMETERS:
- pattern: What to search for (file names OR content text)
- literalSearch: Use exact string matching instead of regex (default: false)
- filePattern: Optional filter to limit search to specific file types (e.g., "*.js", "package.json")
- ignoreCase: Case-insensitive search (default: true). Works for both file names and content.
- earlyTermination: Stop search early when exact filename match is found (optional: defaults to true for file searches, false for content searches)
DECISION EXAMPLES:
- "find package.json" → searchType="files", pattern="package.json" (specific file)
- "find authentication components" → searchType="content", pattern="authentication" (looking for functionality)
- "locate all React components" → searchType="files", pattern="*.tsx" or "*.jsx" (file pattern)
- "find TODO comments" → searchType="content", pattern="TODO" (text in files)
- "show me login files" → AMBIGUOUS → run both: files with "login" AND content with "login"
- "find config" → AMBIGUOUS → run both: config files AND files containing config code
COMPREHENSIVE SEARCH EXAMPLES:
- Find package.json files: searchType="files", pattern="package.json"
- Find all JS files: searchType="files", pattern="*.js"
- Search for TODO in code: searchType="content", pattern="TODO", filePattern="*.js|*.ts"
- Search for exact code: searchType="content", pattern="toast.error('test')", literalSearch=true
- Ambiguous request "find auth stuff": Run two searches:
1. searchType="files", pattern="auth"
2. searchType="content", pattern="authentication"
Ambiguous requests can combine file-name and content searches for broader coverage.
This tool starts a background search process and returns immediately with a session ID.
Results are available through get_more_search_results, and stop_search can end the search early.
Perfect for large directories where you want to see results immediately and
have the option to cancel if the search takes too long or you find what you need.
Absolute paths are the most reliable because they do not depend on the current working directory. Paths are automatically normalized regardless of slash direction. Relative paths depend on the current working directory, and tilde paths (~/...) may not resolve in every context. Absolute paths are generally the most reliable.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.Inputs: path (required), pattern (required), origin, ignoreCase, +8 more.
stop_searchA
Stop an active search.
Stops the background search process gracefully. Use this when you've found
what you need or if a search is taking too long. Similar to force_terminate
for terminal processes.
The search will still be available for reading final results until it's
automatically cleaned up after 5 minutes.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.Inputs: sessionId (required).
write_fileADestructive
Write or append to file contents.
PDF creation is handled by the dedicated write_pdf tool.
Existing DOCX content can be edited with edit_block. New DOCX files can be created here; markdown headings (#, ##, ###) are converted to styled DOCX paragraphs.
CHUNKED WRITES:
- Repeated calls with mode='rewrite' followed by mode='append' are supported for longer files.
- Chunks of roughly 25-30 lines minimize latency when writing long text, multiple files, documentation, code, or configuration files.
- Files over 50 lines are still written successfully but may generate performance notes.
- For continuation after a partial write, the existing file state can be inspected before appending the remaining content.
FORMAT HANDLING (by extension):
- Text files: String content
- Excel (.xlsx, .xls, .xlsm): JSON 2D array or {"SheetName": [[...]]}
Example: '[["Name","Age"],["Alice",30]]'
Only works within allowed directories.
Absolute paths are the most reliable because they do not depend on the current working directory. Paths are automatically normalized regardless of slash direction. Relative paths depend on the current working directory, and tilde paths (~/...) may not resolve in every context. Absolute paths are generally the most reliable.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.Inputs: path (required), content (required), mode, origin.
write_pdfADestructive
Create a new PDF file or modify an existing one.
Dedicated PDF creation and modification tool.
OUTPUT FILES:
- Creating a PDF requires 'outputPath' with a new filename (e.g., "result_01.pdf", "analysis_2025_01.pdf", etc.).
MODES:
1. CREATE NEW PDF:
- Pass a markdown string as 'content'.
write_pdf(path="doc.pdf", content="# Title\n\nBody text...")
2. MODIFY EXISTING PDF:
- Pass array of operations as 'content'.
- Modifications preserve the original PDF and require a different filename in 'outputPath'.
- The result includes the original and output paths for reference.
write_pdf(path="doc.pdf", content=[
{ type: "delete", pageIndexes: [0, 2] },
{ type: "insert", pageIndex: 1, markdown: "# New Page" }
])
OPERATIONS:
- delete: Remove pages by 0-based index.
{ type: "delete", pageIndexes: [0, 1, 5] }
- insert: Add pages at a specific 0-based index.
{ type: "insert", pageIndex: 0, markdown: "..." }
{ type: "insert", pageIndex: 5, sourcePdfPath: "/path/to/source.pdf" }
PAGE BREAKS:
To force a page break, use this HTML element:
<div style="page-break-before: always;"></div>
Example:
"# Page 1\n\n<div style=\"page-break-before: always;\"></div>\n\n# Page 2"
ADVANCED STYLING:
HTML/CSS and inline SVG are supported for:
- Text styling: colors, sizes, alignment, highlights
- Boxes: borders, backgrounds, padding, rounded corners
- SVG graphics: charts, diagrams, icons, shapes
- Images: <img src="/absolute/path/image.jpg" width="300" /> or 
Supports standard markdown features including headers, lists, code blocks, tables, and basic formatting.
Only works within allowed directories.
Absolute paths are the most reliable because they do not depend on the current working directory. Paths are automatically normalized regardless of slash direction. Relative paths depend on the current working directory, and tilde paths (~/...) may not resolve in every context. Absolute paths are generally the most reliable.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.Inputs: path (required), content (required), options, outputPath.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 25 tools
Most tools target a distinct resource+action pair (read_file, write_file, list_directory, start_search, read_process_output), and descriptions actively steer between similar ones (write_pdf vs write_file, list_processes vs list_sessions). The main overlap is kill_process vs force_terminate, which both terminate processes and whose own descriptions cross-reference each other, plus the trio list_processes/list_sessions/list_searches which requires careful reading to distinguish.
Nearly all 25 tools follow a snake_case verb_noun pattern (start_process, read_file, stop_search, get_file_info, set_config_value). Minor deviations are force_terminate (verb only, no object) and the unusually long give_feedback_to_desktop_commander, but the overall convention is predictable.
At 25 tools the surface is at the heavy end for what is really four domains (filesystem, terminal sessions, search, config). Several tools feel peripheral to the core mission — give_feedback_to_desktop_commander, get_usage_stats, get_recent_tool_calls — and inflate the set without adding execution capability.
Filesystem, process/session, search, and PDF/DOCX/Excel lifecycle coverage is strong, including paginated reads, edits, and session termination. The notable gap is file/directory deletion (no delete_file or remove_directory), though agents can work around this via start_process shell commands.
Maintenance
Related MCP Connectors
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Related MCP Servers
- AlicenseAqualityDmaintenanceAllows Claude to execute terminal commands on your computer and perform file system operations including surgical code editing with diff-based replacements.19740,317 npm7MIT
- AlicenseAqualityDmaintenanceA server that lets Claude desktop app execute terminal commands on your computer and edit files through Model Context Protocol, featuring command execution, process management, and advanced file operations.19740,317 npm6MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with B\&R Automation Studio projects by building code, running ARsim simulators, and reading or writing OPC UA variables. It facilitates industrial automation development and real-time variable integration through natural language commands.17MIT
- AlicenseAqualityCmaintenanceGive Claude Desktop terminal, filesystem, and background-job access on your local Linux machine. Zero-dependency MCP extension, MIT-licensed.85MIT
Appeared in Searches
- MCP server for file system access (read, write, execute) on Windows for Claude Desktop
- File Editing Tools and Services
- Testing Local AI Agents in LMStudio for Computer Use and Code Execution Tasks
- AI-powered IDEs for project analysis and development
- Official Google MCP server for transferring Markdown files to Google Sheets