desktop-commander-overview

Desktop Commander MCP

Desktop Commander 让 Agent 能够访问用户的实际计算机，包括文件、文件夹、终端、进程、结构化文档，以及通过 SSH 可访问的远程计算机。工具的详细架构（参数、返回结构、特定格式的行为）由 MCP 本身提供；本技能介绍这些工具能做什么，以及如何将它们组合成常见工作流。

此 MCP 为 Agent 提供的能力

持久 Shell 会话。 Desktop Commander 会让已启动的进程或会话在多次工具调用之间保持运行状态。在单个长期运行的 Shell、REPL 或 SSH 会话中，状态会持续保留，包括环境变量、工作目录、已激活的虚拟环境、打开的连接和 REPL 变量。因此，Agent 可以先执行 cd、激活虚拟环境，然后在多轮对话之后，继续向同一会话发送命令或代码，无需重新设置。（注意：单独调用 start_process 会开启不同的会话，彼此之间不会共享 Shell 状态；持久性仅在单个会话内有效，不会跨会话保留。）

长时间运行的进程。 在后台启动开发服务器、监视器、构建任务、训练任务或测试套件，同时继续处理其他工作。MCP 会返回一个进程句柄，Agent 可以在多轮对话中查看输出、与进程交互或终止进程。长时间运行的命令无需阻塞工作流，等待前台命令退出。

访问 IDE 工作区之外的文件系统。 读取、写入、移动、列出和检查用户授权范围内任意位置的文件，包括 Downloads、Documents、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 / 内存问题。

示例工作流

每个示例都会列出实际使用的工具调用顺序。下方调用使用伪代码简写（tool_name("arg", flag=value)）；实际工具接收对象形式的参数。工具说明和完整参数集由 MCP 本身提供。

“调试此生产问题”

在运行会影响生产环境的 SSH 命令之前，请说明计划执行的操作；如果风险不可忽视，请先征得用户确认。

start_process("ssh [email protected]", timeout_ms=...) 会打开一个长期运行的 SSH 会话并返回 PID。interact_with_process(pid, "tail -f /var/log/app.log\n") 会开始持续输出日志。后续轮次中，使用 read_process_output(pid, offset=-50) 查看实时输出的最后 50 行，使用 interact_with_process(pid, "...") 在同一会话中运行诊断命令。完成后，使用 force_terminate(pid) 关闭会话——对于通过 start_process 打开的会话，force_terminate 是正确的清理工具；kill_process 用于终止通过 list_processes 找到的任意 OS PID。

“将此部署到 staging”

在执行部署、重启、迁移或其他会改变环境的命令之前，请总结计划执行的操作并征得用户确认，除非用户已经明确要求执行该具体操作。

使用 start_process 运行部署命令（可以是脚本、通过 SSH 管道传递的命令，或 kubectl/gh 等）。使用 read_process_output 跟踪输出并发现错误。如果部署需要交互式确认，则使用 interact_with_process(pid, "yes\n")。Agent 会持续监控会话，直到操作完成或回滚。

“运行开发服务器并迭代 API”

start_process("npm run dev", timeout_ms=...) 会让服务器持续运行。然后，Agent 会循环执行：对路由文件使用 edit_block，使用 read_process_output(pid, offset=-30) 查看服务器重新加载情况，使用 start_process("curl -s http://localhost:3000/api/...") 进行一次性测试，然后重复此流程。代码变更之间无需重启开发服务器。

“重构此单体仓库中的代码”

使用 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) 翻页查看结果，直到搜索完成——只有到那时，才能确认没有剩余匹配项。

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

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——非零 offset 会将读取模式切换为 XML 模式。从输出中复制 XML 片段作为 old_string，并调用 edit_block(file_path, old_string, new_string) 写入改写后的 XML。用户得到的是实际的 .xlsx 和 .docx 文件，而不是重新生成的近似版本。

“将 Q3 报告生成为 PDF”

编写 Markdown 内容（标题、表格、通过嵌入式 HTML 添加的图表），然后调用 write_pdf 将其渲染为新的 PDF 文件。MCP 的 write_pdf 工具说明中列出了确切的参数和文件名规则——请遵循这些规则。

“在此 PDF 中插入封面页”

write_pdf 还支持通过操作数组（插入/删除页面）修改现有 PDF。对于会生成新 PDF 的现有 PDF 编辑，请使用此功能——例如添加封面页、删除某个部分，或合并其他文件中的内容。有关操作格式和参数规则，请参阅 write_pdf 工具说明。

“分析这个 200MB 的 CSV”

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 本身建议对任何本地数据文件分析都采用这种工作流。

“运行一个快速 Node 脚本”

start_process("node:local", timeout_ms=...) 会在 MCP 服务本身上打开一种无状态的 Node 执行模式——支持 ES 导入。start_process 会打开运行器；每段 JS 都通过 interact_with_process(pid, "<your JS here>") 发送并独立运行（调用之间不共享状态）。适合一次性转换任务，这类任务不值得一直保持 REPL 运行。不要试图将代码放进 start_process 的命令参数中——那里只能填写运行器类型（node:local）。

“解释这个代码库”

使用 list_directory(path=repo_root, depth=3) 查看结构。使用 start_search(pattern="export ", path=repo_root, searchType="content") 查找公开接口。使用 read_multiple_files(paths=[entrypoints]) 阅读实际代码。Agent 可以继续缩小搜索范围，无需再次询问用户应该查看哪里。

“整理我的 Downloads 文件夹”

先将路径解析为绝对路径（例如，/Users/<user>/Downloads，而不是 ~/Downloads）。然后使用 list_directory(path="/Users/<user>/Downloads", depth=1) 查看其中的内容。使用 start_search(pattern="*.pdf", path="/Users/<user>/Downloads", searchType="files") 搜索 PDF，其他类型也可照此处理。使用 create_directory 新建文件夹。逐个使用 move_file 移动项目。执行有破坏性的操作前，先预览移动计划。

“帮我了解情况——上次会话发生了什么？”

get_recent_tool_calls(maxResults=200) 会返回近期活动及其参数和输出。list_sessions 会显示仍在运行的终端会话。list_searches 会显示正在进行的搜索。list_processes 会显示仍在运行的进程。结合这些信息，无需用户回顾也能还原工作进展。

“为什么 REPL 没有响应？”

查看 list_sessions——如果 Blocked: true，说明 REPL 正在等待输入，而不是卡住了。使用 read_process_output(pid, offset=-100) 查看它最后输出的内容（通常是提示符）。使用 interact_with_process(pid, "<the input it's waiting for>\n") 解除阻塞。

核心工具清单

按 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

约定

优先使用绝对路径。 相对路径可能会因工作目录不同而失败，波浪号路径（~/...）也不一定能在所有上下文中展开。绝对路径最可靠；尽可能传入绝对路径。

允许目录范围。 文件操作只能在用户配置的 allowedDirectories 范围内进行。预期 list_directory 输出中会出现 [DENIED] 标记，且路径超出范围时，read_file / write_file 会拒绝操作。将被拒绝的路径告知用户，不要重试。

在 macOS 上运行时： 默认 shell 是 zsh。使用 python3，不要使用 python。一些 GNU 工具的名称带有前缀（例如 GNU sed 的 gsed）。常见的包管理器是 brew。open 可从终端打开文件 / 应用，mdfind 是通过 Spotlight 按确切文件名搜索的最快方式。请通过 get_config（或在 shell 中检查 process.platform / uname）检测主机平台，再判断是否适用以上规则——Windows 和 Linux 主机的行为有所不同。

分页。 长输出（文件读取、进程输出、搜索结果）都支持 offset 和 length。负数偏移量可从末尾读取（尾部模式）。使用这些参数，而不要将大量结果全部输出到上下文中。