Back to Details

desktop-commander-overview

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Desktop Commander MCP

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.
Desktop Commander 让Agent能够访问用户的真实计算机——包括文件、文件夹、终端、进程、结构化文档，以及可通过SSH访问的远程机器。这些工具的详细模式（参数、返回格式、特定格式的行为）都存储在MCP本身中；本技能将解释这些工具的功能，以及如何将它们组合成常见工作流。

What this MCP gives the agent

该MCP为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.
持久化Shell会话。Desktop Commander可在多次工具调用期间保持已启动的进程或会话处于活跃状态。在单个长期运行的Shell、REPL或SSH会话中，状态会持续保留——环境变量、工作目录、激活的virtualenv、打开的连接、REPL变量等，因此Agent可以执行
cd
命令、激活venv，之后在多个轮次后仍能向同一个会话发送命令或代码，无需重新配置。（注意：单独的
start_process
调用会打开独立会话，彼此之间不共享Shell状态；状态持久化仅针对单个会话，而非跨会话。）
长时间运行的进程。在后台启动开发服务器、监视器、构建任务、训练运行或测试套件，并继续其他工作。MCP会返回一个进程句柄，Agent可在多个轮次中对其进行日志跟踪、交互或终止操作。长时间运行的命令无需阻塞工作流，等待前台命令退出。
超出IDE工作区的文件系统访问权限。可在用户授权的任意范围内读取、写入、移动、列出和检查文件——包括下载文件夹、文档文件夹、IDE之外的项目文件夹或其他授权文件夹。适用于整理清理任务、批量文档处理，以及任何不适合在IDE沙箱内完成的“查看同事刚发给我的文件”这类请求。
对现有文件的精准编辑。
edit_block
工具可执行精确字符串查找替换，并内置安全机制：模糊匹配会直接失败，而非静默覆盖错误内容；
expected_replacements
参数可防止部分匹配导致的灾难。相比仅根据读取的片段重写整个文件，这种方式的数据丢失风险更低——不过错误的
old_string
或
expected_replacements
仍可能损坏内容，因此完成编辑前请务必检查修改后的内容。
MCP直接处理二进制和结构化文件。Excel、DOCX和PDF是一等公民——通过特定格式的机制进行读取和修改，而非仅基于文本的近似处理：Excel通过单元格范围JSON操作，DOCX通过原始XML编辑，PDF通过对新输出文件的页面级操作。最终得到的是原始格式的真实文件，而非重新生成的近似版本。图片和PDF会以可查看的内容返回给Agent。
大规模搜索。基于ripgrep的流式搜索，可覆盖整个项目或文件夹树。Agent可选择文件名搜索或文件内容搜索，逐步分页查看结果，避免上下文被大量结果淹没；当查询存在歧义时，还可运行多个并发搜索。
通过SSH访问远程机器。持久化Shell中的长期SSH会话可将Agent转变为真正的运维工具：只需连接一次，之后即可在多个轮次中跟踪日志、运行诊断、部署或调试，无需每次重新连接。
进程管理。列出、检查、跟踪和终止可访问的进程（受操作系统权限限制）。适用于清理之前会话中残留的开发服务器，以及诊断CPU/内存问题。

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.
每个示例都会列出实际的工具序列。以下调用采用伪代码简写形式（
tool_name("arg", flag=value)
）；实际工具接受对象类型的参数。工具描述和完整参数集可在MCP本身中查看。

"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
.
在运行影响生产环境的SSH命令前，若存在非 trivial 的风险，请先解释预期操作并获得用户确认。
start_process("ssh user@prod.example.com", timeout_ms=...)
会打开一个长期SSH会话并返回PID。
interact_with_process(pid, "tail -f /var/log/app.log\ ")
开始流式传输日志。后续轮次中：
read_process_output(pid, offset=-50)
可查看最近到达的50行日志，
interact_with_process(pid, "...")
可在同一个会话中运行诊断命令。完成后使用
force_terminate(pid)
关闭会话——对于
start_process
打开的会话，
force_terminate
是正确的清理工具；
kill_process
用于通过
list_processes
找到的任意操作系统PID。

"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.
在执行部署、重启、迁移或其他会改变环境的命令前，除非用户已明确要求执行该操作，否则请先总结操作内容并获得用户确认。
使用
start_process
执行部署命令（可以是脚本、SSH管道命令或
kubectl
/
gh
等工具）。通过
read_process_output
跟踪输出并发现错误。如果部署需要交互式确认，执行
interact_with_process(pid, "yes\ ")
。会话会保持活跃，Agent会持续监控完成状态或回滚情况。

"Run the dev server and iterate on the API"

“启动开发服务器并迭代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.
start_process("npm run dev", timeout_ms=...)
保持服务器运行。随后Agent会循环执行以下操作：对路由文件执行
edit_block
，
read_process_output(pid, offset=-30)
查看服务器重载日志，
start_process("curl -s http://localhost:3000/api/...")
进行一次性测试，重复上述步骤。开发服务器无需在代码变更之间重启。

"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.
start_search(pattern="oldFunctionName", path=repo_root, searchType="content")
定位所有调用位置。
get_more_search_results(sessionId)
分页查看结果。
read_multiple_files(paths=[...])
在上下文中确认模糊匹配的结果。对每个位置执行
edit_block(file_path, old_string, new_string)
，当同一子字符串在单个文件中合法出现多次时，设置
expected_replacements
参数。通过重新运行
start_search
搜索旧名称，并使用
get_more_search_results(sessionId)
分页查看结果，直到搜索完成且确认无剩余匹配项，以此验证重构效果。

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

“更新此电子表格中的Q3数据并调整报告中的摘要”

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.
read_file(path="/.../q3.xlsx", sheet="Revenue", range="A1:F50")
会以JSON二维数组形式返回现有数据。
edit_block(file_path="/.../q3.xlsx", range="Revenue!C12:C24", content=[[12345], ...])
会就地更新单元格。对于报告，DOCX编辑需要两步读取流程：首先执行
read_file(path="/.../report.docx")
（offset=0）返回文档的大纲（标题+段落文本），以便定位摘要部分。然后执行
read_file(path="/.../report.docx", offset=N, length=...)
，其中**
N > 0
**会将读取模式切换为XML模式，返回该部分的底层原始XML。从输出中复制XML片段作为
old_string
，并调用
edit_block(file_path, old_string, new_string)
传入改写后的XML。用户最终会得到真实的
.xlsx
和
.docx
文件，而非重新生成的近似版本。

"Generate the Q3 report as a PDF"

“将Q3报告生成为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.
编写Markdown内容（标题、表格、通过嵌入HTML实现的图表），然后调用
write_pdf
将其渲染为新的PDF文件。MCP的
write_pdf
工具描述中指定了确切的参数和文件名规则，请遵循该规则。

"Insert a cover page into this PDF"

“在此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.
write_pdf
还支持通过操作数组（插入/删除页面）修改现有PDF。可用于对现有PDF进行编辑并生成新文件——比如添加封面、删除章节、合并其他文件的内容。请查看
write_pdf
工具描述中的操作格式和参数规则。

"Analyze this 200MB CSV"

“分析这个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.
start_process("python3 -i", timeout_ms=...)
打开Python REPL并返回PID。
interact_with_process(pid, "import pandas as pd; df = pd.read_csv('/abs/path.csv')")
一次性加载文件。后续的所有查询——
df.describe()
、
df.groupby('col').size()
、绘制图表——都在同一个已加载的REPL中运行。无需重新导入库，也无需重新加载数据框。MCP本身推荐将此工作流用于任何本地数据文件分析。

"Run a quick Node script"

“运行一个快速Node脚本”

start_process("node:local", timeout_ms=...)
opens a stateless Node execution mode on the MCP server itself — ES imports supported. 
start_process
opens the runner; each piece of JS is sent via 
interact_with_process(pid, "<your JS here>")
and runs independently (no shared state between calls). Good for one-shot transformations where keeping a long-lived REPL alive isn't worth it. Don't try to put code into the 
start_process
command argument — only the runner type (
node:local
) goes there.
start_process("node:local", timeout_ms=...)
在MCP服务器上打开无状态的Node执行模式——支持ES导入。
start_process
启动运行器；每段JS代码通过
interact_with_process(pid, "<your JS here>")
发送，且独立运行（调用之间无共享状态）。适用于无需保持长期REPL活跃的一次性转换任务。请勿尝试将代码放入
start_process
命令参数中——仅运行器类型（
node:local
）需放在此处。

"Explain this codebase"

“解释这个代码库”

list_directory(path=repo_root, depth=3)
for shape. 
start_search(pattern="export ", path=repo_root, searchType="content")
to find the public surface. 
read_multiple_files(paths=[entrypoints])
for the actual code. The agent can keep narrowing without re-asking the user where to look.
list_directory(path=repo_root, depth=3)
查看代码库结构。
start_search(pattern="export ", path=repo_root, searchType="content")
查找公共接口。
read_multiple_files(paths=[entrypoints])
读取实际代码。Agent无需反复询问用户查找位置，即可逐步缩小范围。

"Organize my Downloads folder"

“整理我的下载文件夹”

Resolve the path to absolute first (e.g., 
/Users/<user>/Downloads
, not 
~/Downloads
). Then 
list_directory(path="/Users/<user>/Downloads", depth=1)
to see what's there. 
start_search(pattern="*.pdf", path="/Users/<user>/Downloads", searchType="files")
and similar for other types. 
create_directory
for new folders. 
move_file
per item. Preview the move plan before executing destructive ops.
先将路径解析为绝对路径（例如
/Users/<user>/Downloads
，而非
~/Downloads
）。然后执行
list_directory(path="/Users/<user>/Downloads", depth=1)
查看文件夹内容。
start_search(pattern="*.pdf", path="/Users/<user>/Downloads", searchType="files")
，并对其他文件类型执行类似操作。使用
create_directory
创建新文件夹，使用
move_file
移动每个文件。在执行破坏性操作前，请预览移动计划。

"Onboard me — what was happening last session?"

“带我快速上手——上一个会话在做什么？”

get_recent_tool_calls(maxResults=200)
returns recent activity with arguments and outputs. 
list_sessions
shows still-running terminal sessions. 
list_searches
shows in-flight searches. 
list_processes
shows what's still alive. Together they reconstruct the work without asking the user to recap.
get_recent_tool_calls(maxResults=200)
返回最近的操作记录，包括参数和输出。
list_sessions
显示仍在运行的终端会话。
list_searches
显示正在进行的搜索。
list_processes
显示仍在运行的进程。这些信息可共同重构之前的工作内容，无需用户复述。

"Why isn't the REPL responding?"

“为什么REPL没有响应？”

list_sessions
— if 
Blocked: true
, the REPL is waiting for input rather than hung. 
read_process_output(pid, offset=-100)
to see what it last printed (often a prompt). 
interact_with_process(pid, "<the input it's waiting for>\n")
unblocks it.
list_sessions
——如果显示
Blocked: true
，说明REPL正在等待输入，而非挂起。
read_process_output(pid, offset=-100)
查看最后输出的内容（通常是提示符）。
interact_with_process(pid, "<the input it's waiting for>\ ")
可解除阻塞。

Core tool inventory

核心工具清单

Grouped index of the tools an agent reaches for most often. Not exhaustive — the MCP exposes additional config / diagnostics / feedback tools beyond this list. Detailed parameters and return shapes for every tool are in the MCP's own tool descriptions.
  • Process / shell: 
    start_process
    , 
    interact_with_process
    , 
    read_process_output
    , 
    list_processes
    , 
    list_sessions
    , 
    kill_process
    , 
    force_terminate
  • Files (read/write): 
    read_file
    , 
    read_multiple_files
    , 
    write_file
    , 
    edit_block
    , 
    write_pdf
  • Filesystem: 
    list_directory
    , 
    get_file_info
    , 
    move_file
    , 
    create_directory
  • Search: 
    start_search
    , 
    get_more_search_results
    , 
    list_searches
    , 
    stop_search
  • Diagnostics / config: 
    get_recent_tool_calls
    , 
    get_config
Agent最常用工具的分组索引。并非完整清单——MCP还提供了此清单之外的配置/诊断/反馈工具。每个工具的详细参数和返回格式可在MCP自身的工具描述中查看。
  • 进程/Shell：
    start_process
    , 
    interact_with_process
    , 
    read_process_output
    , 
    list_processes
    , 
    list_sessions
    , 
    kill_process
    , 
    force_terminate
  • 文件（读/写）：
    read_file
    , 
    read_multiple_files
    , 
    write_file
    , 
    edit_block
    , 
    write_pdf
  • 文件系统：
    list_directory
    , 
    get_file_info
    , 
    move_file
    , 
    create_directory
  • 搜索：
    start_search
    , 
    get_more_search_results
    , 
    list_searches
    , 
    stop_search
  • 诊断/配置：
    get_recent_tool_calls
    , 
    get_config

Conventions

约定

Prefer absolute paths. Relative paths may fail depending on the working directory, and tilde paths (
~/...
) may not expand in all contexts. Absolute paths are the most reliable; pass them whenever you can.
Allowed-directory scope. File operations only work inside the user's configured 
allowedDirectories
. Expect 
[DENIED]
markers in 
list_directory
output and rejections from 
read_file
/ 
write_file
when the path is out of scope. Surface the rejected path to the user — don't retry.
When running on macOS: default shell is zsh. Use 
python3
not 
python
. Some GNU tools have prefixed names (
gsed
for GNU sed). 
brew
is the typical package manager. 
open
opens files / apps from the terminal, 
mdfind
is the fastest path to exact-filename search via Spotlight. Detect the host platform via 
get_config
(or by inspecting 
process.platform
/ 
uname
from a shell) before assuming any of the above — Windows and Linux hosts behave differently.
Pagination. Long outputs (file reads, process output, search results) all support 
offset
and 
length
. Negative offsets read from the end (tail mode). Use these instead of dumping huge results into context.
优先使用绝对路径。相对路径可能会因工作目录不同而失败，波浪线路径（
~/...
）在某些环境中可能无法展开。绝对路径是最可靠的；只要可能，请使用绝对路径。
允许的目录范围。文件操作仅在用户配置的
allowedDirectories
范围内有效。当路径超出范围时，
list_directory
输出中会出现
[DENIED]
标记，
read_file
/
write_file
会拒绝执行操作。请将被拒绝的路径告知用户——不要重试。
在macOS上运行时：默认Shell是zsh。使用
python3
而非
python
。部分GNU工具带有前缀名称（如
gsed
对应GNU sed）。
brew
是常用的包管理器。
open
可从终端打开文件/应用，
mdfind
是通过Spotlight进行精确文件名搜索的最快方式。在假设上述规则前，请通过
get_config
（或从Shell中检查
process.platform
/
uname
）检测主机平台——Windows和Linux主机的行为有所不同。
分页。长输出（文件读取、进程输出、搜索结果）均支持
offset
和
length
参数。负偏移量表示从末尾读取（尾部模式）。请使用这些参数，避免将大量结果直接放入上下文。",