desktop-commander-overview

What this skill does

# 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 [email protected]", 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)` per site, with `expected_replacements` set when the same substring legitimately appears multiple times in one file. Verify by re-running `start_search` on the old name and paging the results with `get_more_search_results(sessionId)` until the run completes — only then can you confirm zero remaining hits.

### "Update the Q3 numbers in this spreadsheet and tweak the summary in the report"

`read_file(path="/.../q3.xlsx", sheet="Revenue", range="A1:F50")` returns the existing numbers as a JSON 2D array. `edit_block(file_path="/.../q3.xlsx", range="Revenue!C12:C24", content=[[12345], ...])` updates the cells in place. For the report, DOCX editing is a two-read flow: first `read_file(path="/.../report.docx")` (offset 0) returns the document's outline (headings + paragraph text) so you can locate the summary section. Then `read_file(path="/.../report.docx", offset=N, length=...)` with **`N > 0`** returns the raw underlying XML around that section — a non-zero offset is what flips the read into XML mode. Copy an XML fragment from that output as `old_string` and call `edit_block(file_path, old_string, new_string)` with the rewritten XML. The user gets back real `.xlsx` and `.docx` files, not regenerated approximations.

### "Generate the Q3 report as a PDF"

Compose markdown content (header, table, charts via embedded HTML), then call `write_pdf` to render it to a new PDF file. The MCP's `write_pdf` tool description specifies the exact parameters and filename rules — follow that.

### "Insert a cover page into this PDF"

`write_pdf` also supports modifying existing PDFs via an operations array (insert / delete pages). Use it for existing-PDF edits that produce a new PDF — adding a cover page, removing a section, merging in content from another file. See the `write_pdf` tool description for the operation shapes and parameter rules.

### "Analyze this 200MB CSV"

`start_process("python3 -i", timeout_ms=...)` opens a Python REPL and returns a PID. `interact_with_process(pid, "import pandas as pd; df = pd.read_csv('/abs/path.csv')")` loads it once. Every subsequent question — `df.describe()`, `df.groupby('col').size()`, plot a chart — runs in the same already-loaded REPL. Libraries don't re-import, the dataframe doesn't re-load. The MCP itself recommends this workflow for any local data-file analysis.

### "Run a quick Node s