desktop-commander

Desktop Commander

Quick start

Goal: use Desktop Commander MCP to turn “files / processes / search / edits” into verifiable tool calls (small, safe steps) instead of treating the machine as a black box.

Most common entry points:

• Read content: mcp__desktop-commander__read_file (paging, negative offset tail, PDF/image/Excel/URL).
• Small edits: mcp__desktop-commander__edit_block (targeted text replace / Excel range update).
• Large edits: mcp__desktop-commander__write_file in chunks (respect fileWriteLineLimit).
• Interactive work: mcp__desktop-commander__start_process + mcp__desktop-commander__interact_with_process + mcp__desktop-commander__read_process_output.

Official notes + tool list: skills/desktop-commander/references/desktop-commander.md.

Workflow decision tree

1. Do I need to find something?

• File names/paths: mcp__desktop-commander__start_search (searchType="files") → mcp__desktop-commander__get_more_search_results
• File contents: mcp__desktop-commander__start_search (searchType="content") → paginate → mcp__desktop-commander__stop_search when done

2. Do I need to read or change content?

• Read: mcp__desktop-commander__read_file (use offset/length; use offset=-N for tail)
• Small change: mcp__desktop-commander__edit_block (default replaces 1 occurrence; use expected_replacements for multiple)
• Large change: mcp__desktop-commander__write_file (mode="rewrite" then mode="append" chunked)

3. Do I need to run commands / keep sessions?

• One-off commands: mcp__desktop-commander__start_process (shell command) + read output
• REPL / SSH / DB / dev server: start_process → interact_with_process → read_process_output

4. Is this a high-risk operation (config changes, killing processes, bulk edits/moves, any data loss)?

• Explain impact + rollback first; require explicit user confirmation before executing.
• Prefer making config changes in a separate chat (official guidance).

Recipes

Reading files

• Text/code: read_file with pagination; logs: offset=-200 (tail-like).
• Multiple files: read_multiple_files to reduce round trips.
• URLs: read_file with isUrl: true for web content/images.

Editing files

• Targeted replace: edit_block with minimal unique context; for many occurrences set expected_replacements.
• Rewrites: write_file in 25–30 line chunks (rewrite then append).
• Excel: read via read_file; edit via edit_block with range + 2D array.
• PDFs: only via write_pdf (do not use write_file for PDFs).

Search

• Prefer start_search + get_more_search_results for repo exploration; stop searches you no longer need.
• Use literalSearch: true for patterns with special characters (parentheses, brackets, dots, etc.).

Processes & interaction

• Data analysis: run python3 -i, then use interact_with_process for pandas/numpy workflows.
• Observing long jobs: call read_process_output periodically; to stop use kill_process/force_terminate (high-risk).
• Status: list_sessions / list_processes.

Config & audit

• get_config / set_config_value: use carefully; directory restrictions are not a security boundary for terminal commands.
• get_recent_tool_calls: recover context and debug “what happened”.
• get_usage_stats: usage/performance insight.

Guardrails (must follow)

• Prefer absolute paths; don’t assume OS-specific separators.
• For big changes: read first; keep edits small; chunk writes; keep rollback in mind.
• High-risk actions require explicit confirmation: config changes, killing sessions/processes, bulk file edits/moves, any destructive command.
• Security: allowedDirectories limits filesystem tools, not terminal commands—don’t treat it as sandboxing.

References

• Official notes + tool list: skills/desktop-commander/references/desktop-commander.md