/desktop-commander-overview

name: desktop-commander-overview
description: Use for Desktop Commander MCP capabilities — persistent shells and REPLs, long-running processes, filesystem beyond the workspace, structured files (.xlsx, .docx, .pdf, images) and large local data files such as CSVs, ripgrep search at scale, SSH, or cross-turn state.
version: 0.1.0
audience: agent

Desktop Commander MCP

Desktop Commander gives the agent reach across the user's actual computer — files, folders, terminals, processes, structured documents, and remote machines reachable over SSH. The tools' detailed schemas (parameters, return shapes, format-specific behavior) live in the MCP itself; this skill explains what they enable and how they compose into common workflows.

What this MCP gives the agent

**Persistent shell sessions.** Desktop Commander keeps a started process or session alive across tool calls. Inside a single long-lived shell, REPL, or SSH session, state carries forward — environment variables, working directory, activated virtualenvs, open connections, REPL variables — so the agent can `cd`, activate a venv, then send commands or code into that same session many turns later without re-setup. (Note: separate `start_process` calls open separate sessions and do **not** share shell state with each other; persistence is inside one session, not across them.)

**Long-running processes.** Start a dev server, watcher, build, training run, or test suite in the background and keep working. The MCP returns a process handle the agent can tail, interact with, or terminate across many turns. Long-running commands don't need to block the workflow waiting for a foreground command to exit.

**Filesystem reach beyond the IDE workspace.** Read, write, move, list, and inspect files anywhere the user has granted scope — Downloads, Documents, project folders outside the IDE, or any other granted folders. Useful for organize-and-clean tasks, batch document work, and any "look at the file my coworker just sent me" request that doesn't fit inside the IDE sandbox.

**Surgical edits to existing files.** The `edit_block` tool does exact-string find-and-replace with built-in safety: ambiguous matches fail loudly instead of silently overwriting the wrong thing, and an `expected_replacements` count prevents partial-match disasters. Lower data-loss risk than rewriting whole files based on the slice you happened to read — though a wrong `old_string` or wrong `expected_replacements` can still corrupt content, so review the changed content before considering the edit done.

**Binary and structured files handled directly by the MCP.** Excel, DOCX, and PDF are first-class — read and modified through format-specific mechanisms rather than text-only approximations: Excel via cell-range JSON, DOCX via raw-XML edits, PDF via page-level operations on a new output file. The result is the real file in its original format, not a regenerated approximation. Images and PDFs return as viewable content for the agent.

**Search at scale.** Streaming, ripgrep-backed search across whole projects or folder trees. The agent picks between filename search and in-file content search, pages through results progressively without flooding context, and runs multiple concurrent searches when the query is ambiguous.

**Remote machines via SSH.** A long-lived SSH session inside a persistent shell turns the agent into a real ops tool: connect once, then tail logs, run diagnostics, deploy, or debug across many turns without reconnecting each step.

**Process management.** List, inspect, tail, and kill accessible processes (subject to OS permissions). Useful for cleaning up stale dev servers from previous sessions and for diagnosing CPU / memory issues.

Example workflows

Each example names the actual tool sequence. Calls below are written in pseudocode shorthand (`tool_name("arg", flag=value)`); the real tools take object-shaped arguments. Tool descriptions and full parameter sets live in the MCP itself.

"Debug this production issue"

Before running production-impacting SSH commands, explain the intended action and get user confirmation when the risk is non-trivial.

`start_process("ssh user@prod.example.com", timeout_ms=...)` opens a long-lived SSH session and returns a PID. `interact_with_process(pid, "tail -f /var/log/app.log\n")` starts streaming logs. Subsequent turns: `read_process_output(pid, offset=-50)` to see the last 50 lines as they arrive, `interact_with_process(pid, "...")` to run diagnostic commands in the same session. `force_terminate(pid)` to close the session when done — for sessions opened by `start_process`, `force_terminate` is the correct cleanup tool; `kill_process` is for arbitrary OS PIDs found via `list_processes`.

"Deploy this to staging"

Before deploys, restarts, migrations, or other environment-changing commands, summarize the action and confirm with the user unless they already explicitly asked for that exact operation.

`start_process` for the deploy command (could be a script, an SSH-piped command, or `kubectl`/`gh` etc.). `read_process_output` to track output and surface errors. If the deploy needs an interactive confirmation, `interact_with_process(pid, "yes\n")`. The session stays alive while the agent watches for completion or rollback.

"Run the dev server and iterate on the API"

`start_process("npm run dev", timeout_ms=...)` keeps the server up. The agent then loops: `edit_block` on the route file, `read_process_output(pid, offset=-30)` to see the server's reload, `start_process("curl -s http://localhost:3000/api/...")` for a one-shot test, repeat. The dev server never has to restart between code changes.

"Refactor across this monorepo"

`start_search(pattern="oldFunctionName", path=repo_root, searchType="content")` scopes every call site. `get_more_search_results(sessionId)` pages through. `read_multiple_files(paths=[...])` confirms ambiguous hits in context. `edit_block(file_path, old_string, new_string)` pe