Desktop Commander MCP

使用 AI 搜索、更新、管理文件并运行终端命令

简短版本。两个关键点：终端命令和基于差异的文件编辑。

目录

• 功能
• 安装
• 使用
• 处理长时间运行的命令
• 正在进行的工作和待办事项
• 媒体链接
• 用户评价
• 常见问题解答
• 贡献
• 许可

这是一个服务器，允许 Claude 桌面应用程序通过 Model Context Protocol (MCP) 在您的计算机上执行长时间运行的终端命令并管理进程。它基于 MCP 文件系统服务器 构建，以提供额外的搜索和替换文件编辑功能。

功能

• 执行带有输出流的终端命令
• 命令超时和后台执行支持
• 进程管理（列出和终止进程）
• 长时间运行命令的会话管理
• 完整的文件系统操作：
  • 读写文件
  • 创建/列出目录
  • 移动文件/目录
  • 搜索文件
  • 获取文件元数据
  • 代码编辑功能：
    • 对小改动进行手术式的文本替换
    • 对大改动进行完整的文件重写
    • 多文件支持
    • 基于模式的替换
    • 使用 vscode-ripgrep 在文件夹中递归搜索代码或文本

安装

首先，请确保您已下载并安装了 Claude 桌面应用程序，并且已经安装了 npm。

选项 1：通过 npx 安装

只需在终端中运行以下命令：

npx @wonderwhy-er/desktop-commander@latest setup

对于调试模式（允许 Node.js 检查器连接）：

npx @wonderwhy-er/desktop-commander@latest setup --debug

如果正在运行 Claude，请重启它。

选项 2：通过 Smithery 安装

要通过 Smithery 自动为 Claude 桌面应用程序安装 Desktop Commander：

npx -y @smithery/cli install @wonderwhy-er/desktop-commander --client claude

选项 3：手动添加到 claude_desktop_config

将此条目添加到您的 claude_desktop_config.json 中：

• 在 Mac 上：~/Library/Application\ Support/Claude/claude_desktop_config.json
• 在 Windows 上：%APPDATA%\Claude\claude_desktop_config.json
• 在 Linux 上：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "desktop-commander": {
      "command": "npx",
      "args": [
        "-y",
        "@wonderwhy-er/desktop-commander"
      ]
    }
  }
}

如果正在运行 Claude，请重启它。

选项 4：本地检出

1. 克隆并构建：

git clone https://github.com/wonderwhy-er/ClaudeComputerCommander.git
cd ClaudeComputerCommander
npm run setup

如果 Claude 正在运行，请重启它

设置命令将：

• 安装依赖项
• 构建服务器
• 配置 Claude 的桌面应用程序
• 如果需要，将 MCP 服务器添加到 Claude 的配置中

使用方法

服务器提供以下工具类别：

终端工具

• execute_command：运行带有可配置超时时间的命令
• read_output：获取长时间运行命令的输出
• force_terminate：停止正在运行的命令会话
• list_sessions：查看活动的命令会话
• list_processes：查看系统进程
• kill_process：通过 PID 终止进程
• block_command/unblock_command：管理命令黑名单

文件系统工具

• read_file/write_file：文件操作
• create_directory/list_directory：目录管理
• move_file：移动/重命名文件
• search_files：基于模式的文件搜索
• get_file_info：文件元数据
• search_code：基于 ripgrep 的递归文本和代码搜索

编辑工具

• edit_block：应用外科手术式的文本替换（最适合对文件大小进行小于 20% 的更改）
• write_file：完全重写文件（最适合大于 20% 的大更改或当 edit_block 失败时）

搜索/替换块格式：

filepath.ext
<<<<<<< SEARCH
content to find
=======
new content
>>>>>>> REPLACE

示例：

src/main.js
<<<<<<< SEARCH
console.log("old message");
=======
console.log("new message");
>>>>>>> REPLACE

处理长时间运行的命令

对于可能需要一段时间的命令：

1. execute_command 在超时后返回初始输出
2. 命令在后台继续运行
3. 使用 read_output 和 PID 获取新的输出
4. 如有需要，使用 force_terminate 停止命令

调试

如果您需要调试服务器，可以以调试模式安装它：

# Using npx
npx @wonderwhy-er/desktop-commander@latest setup --debug

# Or if installed locally
npm run setup:debug

这将：

1. 配置 Claude 使用单独的 "desktop-commander" 服务器
2. 启用带有 --inspect-brk=9229 标志的 Node.js 检查器协议
3. 在启动时暂停执行，直到调试器连接
4. 启用额外的调试环境变量

要连接调试器：

• 在 Chrome 中，访问 chrome://inspect 并查找 Node.js 实例
• 在 VS Code 中，使用 "Attach to Node Process" 调试配置
• 其他 IDE/工具可能有类似的 Node.js 调试 "attach" 选项

重要的调试注意事项：

• 服务器将在启动时暂停，直到调试器连接（由于 --inspect-brk 标志）
• 如果在调试过程中看不到活动，请确保已连接到正确的 Node.js 进程
• 可能有多个 Node 进程在运行；请连接到端口 9229 上的进程
• 调试服务器在 Claude 的 MCP 服务器列表中标识为 "desktop-commander-debug"

故障排除：

• 如果 Claude 在尝试使用调试服务器时超时，您的调试器可能没有正确连接
• 当正确连接后，进程会在遇到第一个断点后继续执行
• 连接后，您可以在 IDE 中添加额外的断点

模型上下文协议集成

此项目扩展了 MCP 文件系统服务器，以实现：

• Claude 桌面版的本地服务器支持
• 完整的系统命令执行
• 进程管理
• 文件操作
• 带有搜索/替换功能的代码编辑

作为探索 Claude MCPs 的一部分创建: https://youtube.com/live/TlbjFDbl5Us

已完成

• 2025年3月28日 修复了 "Watching /" JSON 错误 - 实现了自定义的 stdio 传输来处理非 JSON 消息并防止服务器崩溃
• 2025年3月25日 更好的代码搜索 (合并) - 通过上下文感知的结果增强了代码探索功能

正在进行和待办事项

以下功能正在开发或计划中：

• 更好的配置 (进行中) - 改进了允许路径、命令和 shell 环境的设置
• Windows 环境修复 (进行中) - 解决特定于 Windows 平台的问题
• Linux 改进 (进行中) - 提高与各种 Linux 发行版的兼容性
• WSL 支持 - Windows Subsystem for Linux 集成
• SSH 支持 - 远程服务器命令执行
• 安装故障排除指南 - 全面的帮助解决安装问题

网站

访问我们的官方网站 https://desktopcommander.app/ 获取最新信息、文档和更新。

媒体资料

通过以下资源了解更多关于此项目的信息：

文章

Claude 以 MCP 替代 Cursor & Windsurf。这究竟是怎么发生的？ - 详细探讨了带有模型上下文协议能力的 Claude 如何改变开发者的工作流程。

视频

Claude Desktop Commander 视频教程 - 观看如何有效设置和使用 Commander。

AnalyticsIndiaMag 发布的文章

这位开发者放弃了 Windsurf 和 Cursor，转而使用带 MCP 的 Claude

社区

加入我们的 Discord 服务器 获取帮助、分享反馈并与其他用户联系。

用户评价

https://www.youtube.com/watch?v=ly3bed99Dy8&lc=UgyyBt6_ShdDX_rIOad4AaABAg

https://www.youtube.com/watch?v=ly3bed99Dy8&lc=UgztdHvDMqTb9jiqnf54AaABAg

https://www.youtube.com/watch?v=ly3bed99Dy8&lc=UgyQFTmYLJ4VBwIlmql4AaABAg

https://www.youtube.com/watch?v=ly3bed99Dy8&lc=Ugy4-exy166_Ma7TH-h4AaABAg

https://medium.com/@pharmx/you-sir-are-my-hero-62cff5836a3e

贡献

如果您觉得这个项目有用，请考虑在GitHub上给它一个⭐星标！这有助于其他人发现该项目，并鼓励进一步开发。

我们欢迎社区的贡献！无论您发现了错误、有功能请求，还是想贡献代码，以下是如何帮助我们的方式：

• 发现了一个错误？ 在 github.com/wonderwhy-er/ClaudeComputerCommander/issues 上提交一个问题
• 有功能建议？ 在问题部分提交一个功能请求
• 想要贡献代码？ 叉取仓库，创建一个分支，并提交一个拉取请求
• 有问题或讨论？ 在 GitHub 讨论标签中发起讨论

所有贡献，无论大小，都非常感激！

如果您觉得这个工具对您的工作流程很有价值，请考虑支持项目。

常见问题解答

这里是一些常见问题的答案。对于更全面的FAQ，请参阅我们的详细FAQ文档。

什么是 Claude Desktop Commander？

它是一个MCP工具，使Claude Desktop能够访问您的文件系统和终端，将Claude变成一个多功能助手，用于编码、自动化、代码库探索等。

这与Cursor/Windsurf有何不同？

与专注于IDE的工具不同，Claude Desktop Commander提供了一种以解决方案为中心的方法，适用于整个操作系统，而不仅仅是在编码环境中。Claude会完整读取文件而不是分块读取，可以同时处理多个项目，并一次性执行更改，而不需要不断审查。

我需要为API信用付费吗？

不需要。此工具使用Claude Desktop的标准Pro订阅（每月20美元），而不是通过API调用，因此除了订阅费用外，您不会产生额外成本。

最常见的用途是什么？

• 探索和理解复杂的代码库
• 生成图表和文档
• 跨系统自动化任务
• 同时处理多个项目
• 通过精确控制进行手术式代码更改

我在安装或使用该工具时遇到了麻烦。我可以从哪里获得帮助？

加入我们的Discord服务器获取社区支持，查看GitHub问题了解已知问题，或者查阅完整FAQ获取故障排除提示。您也可以访问我们网站的FAQ部分，以获得更友好的用户体验。如果您遇到新问题，请考虑在GitHub上打开一个问题，并附上您的问题详情。

数据收集

在安装和设置过程中，Desktop Commander会收集匿名使用数据以帮助改进工具。这包括：

• 操作系统信息
• Node.js 和 NPM 版本
• 安装方法和shell环境
• 错误消息（如果在设置过程中出现）

这些数据是使用PostHog分析工具收集的，并与机器生成的唯一ID关联。不收集任何个人信息。这有助于我们了解工具如何被使用，并识别常见问题。

我们正在努力在即将到来的版本中添加一个内置的数据收集退出选项。目前，如果您希望退出，您可以在防火墙设置中阻止到 eu.i.posthog.com 的网络连接。

许可证

MIT