desktop-commander-mcp

Desktop Commander MCP

Quick Start

Goal: Use Desktop Commander MCP to turn "files/processes/search/edit" into tool calls that are verifiable, replayable, and risk-controllable, rather than treating the whole machine as a black box.

The 4 most commonly used entry points:

• File reading: prefer mcp__desktop-commander__read_file(supports pagination, negative offset tail-like behavior, PDF/images/Excel/URL).
• Small-scope changes: prefer mcp__desktop-commander__edit_block(precise text replacement/Excel range updates), avoid rewriting the entire file.
• Large-scope changes: use mcp__desktop-commander__write_file to write in chunks (obey fileWriteLineLimit）。
• Long commands/interaction: use mcp__desktop-commander__start_process + mcp__desktop-commander__interact_with_process + mcp__desktop-commander__read_process_output。

For a more complete tool list and key points, see:skills/desktop-commander-mcp/references/desktop-commander-mcp-official.md。

Workflow Decision Tree

1. Do I need to "find something"?

• File name/directory:mcp__desktop-commander__start_search（searchType="files"）→ mcp__desktop-commander__get_more_search_results
• File content/code keywords:mcp__desktop-commander__start_search（searchType="content") → retrieve results in pages → if necessary mcp__desktop-commander__stop_search

1. Do I need to "read content" or "modify content"?

• Read-only:mcp__desktop-commander__read_file(for large files use offset/length; to get the end use offset=-N）
• Small changes:mcp__desktop-commander__edit_block(by default replaces only 1 occurrence; for multiple occurrences use expected_replacements to specify the count)
• Large changes:mcp__desktop-commander__write_file（mode="rewrite" + subsequent mode="append" chunked writes)

1. Do I need to "run commands/maintain sessions"?

• One-off commands (short output is acceptable): use mcp__desktop-commander__start_process to run bash or a specific command
• Interactive REPL/SSH/database/dev server:start_process start → interact_with_process send input → read_process_output pull output

1. Do risky operations involve: configuration changes / terminating processes / bulk file changes / deleting data?

• First clarify the scope of impact and rollback plan; execute only after explicit user confirmation.
• Prefer to make configuration changes in a separate conversation (the official documentation emphasizes this), to avoid expanding access scope "just to solve permissions".

Common Recipes

File Reading

• Read text/code: use mcp__desktop-commander__read_file, for large files use offset/length pagination; to view the end of a log use offset=-200(similar to tail）。
• Read multiple files: use mcp__desktop-commander__read_multiple_files, which saves interaction cost compared with reading in a loop.
• Read URL:mcp__desktop-commander__read_file pass isUrl: true(suitable for pulling web pages/images into context for analysis).

File Editing

• Precise replacement (recommended): use mcp__desktop-commander__edit_block, write old_string/new_string as the smallest uniquely matching context; for multiple replacements be sure to set expected_replacements。
• Rewrite file: use mcp__desktop-commander__write_file in chunks of 25–30 lines, first mode="rewrite", then multiple mode="append"; avoid writing more than fileWriteLineLimit。
• Excel: for reading use read_file, for modification use edit_block 's range + two-dimensional array content.
• PDF: for creation/modification use only mcp__desktop-commander__write_pdf(do not use write_file to write PDF).

Search

• For codebase exploration, prefer mcp__desktop-commander__start_search; when pagination/long searches are needed, use it together with get_more_search_results, and after it is no longer needed stop_search。
• To find a filename:searchType="files"; to find content:searchType="content"; when exact matching of special characters is needed, set literalSearch to true。

Processes and interaction

• Data analysis (recommended):mcp__desktop-commander__start_process run python3 -i → interact_with_process import pandas/numpy → read the file → print the result.
• Observe long tasks: periodically call mcp__desktop-commander__read_process_output to pull new output; when stuck/needing to stop, use mcp__desktop-commander__kill_process or mcp__desktop-commander__force_terminate(high risk, confirm first).
• Troubleshoot status:mcp__desktop-commander__list_sessions / mcp__desktop-commander__list_processes。

Configuration and auditing

• mcp__desktop-commander__get_config / mcp__desktop-commander__set_config_value: use with caution; the official documentation points out that directory restrictions do not constitute a security boundary for "terminal commands".
• mcp__desktop-commander__get_recent_tool_calls: restore context, debug "what did I do before".
• mcp__desktop-commander__get_usage_stats: understand usage and performance.

Constraints and red lines (must be followed)

• Paths: use absolute paths whenever possible; when cross-platform is involved, do not assume separators or drive letters.
• Major changes: first use read_file to confirm the current state; keep changes as local as possible; writes must be chunked and rollback-capable.
• High-risk operations (only do after explicit confirmation): modifying configuration, terminating processes/sessions, batch changes/moving files, any terminal command that may cause data loss.
• Security: the official documentation clearly states that allowedDirectories only restricts file tools, not terminal commands; do not treat it as a "sandbox/isolation".

Reference materials

• Excerpts and tool list:skills/desktop-commander-mcp/references/desktop-commander-mcp-official.md