Desktop Commander

🚀 桌面指挥官MCP

桌面指挥官MCP是一款强大的工具，它允许Claude桌面应用在你的计算机上执行长时间运行的终端命令，并通过模型上下文协议（MCP）管理进程。此外，它还提供了文件搜索、替换和编辑等功能，能显著提升开发效率。

项目状态与链接

🚀 快速开始

这是一个允许Claude桌面应用在你的计算机上执行长时间运行的终端命令，并通过模型上下文协议（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：使用bash脚本安装器（macOS）

对于macOS用户，可以使用自动化的bash安装器，它会检查你的Node.js版本，必要时进行安装，并自动配置桌面指挥官：

curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install.sh | bash

这个脚本会自动处理所有依赖项和配置，提供无缝的设置体验。

选项3：通过Smithery安装

要通过 Smithery 自动为Claude桌面安装桌面指挥官，可以运行：

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

选项4：手动添加到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正在运行，请重启它。

选项5：本地克隆安装

1. 克隆并构建项目：

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

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

设置命令将执行以下操作：

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

更新桌面指挥官

当通过npx（选项1）或Smithery（选项2）安装时，每次重启Claude时，桌面指挥官将自动更新到最新版本，无需手动更新。

对于手动安装的情况，可以再次运行设置命令进行更新。

💻 使用示例

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

终端工具

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

文件系统工具

• read_file/write_file：从本地文件系统或URL读取文件（支持在Claude中直接查看PNG、JPEG、GIF和WebP图像）
• 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

URL支持

• read_file 现在可以从本地文件和URL获取内容
• 示例：使用 isUrl: true 参数的 read_file 从Web资源获取内容
• 处理来自远程源的文本和图像内容
• 图像（本地或来自URL）在Claude的界面中可视化显示，而不是以文本形式显示
• Claude可以查看和分析实际的图像内容
• URL请求的默认超时时间为30秒

📚 详细文档

处理长时间运行的命令

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

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

调试

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

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

# 或者如果是本地安装
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调试 "附加" 选项

重要的调试注意事项：

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

故障排除：

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

模型上下文协议集成

该项目扩展了MCP文件系统服务器，以实现以下功能：

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

此项目是探索Claude MCP的一部分：https://youtube.com/live/TlbjFDbl5Us

已完成的功能

• 2025年4月7日：添加了URL支持 - read_file 命令现在可以从URL获取内容
• 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 with MCPs replaced Cursor & Windsurf. How did that happen? - 详细探讨了具有模型上下文协议功能的Claude如何改变开发者工作流程。
• 视频：Claude Desktop Commander Video Tutorial - 观看如何有效设置和使用指挥官。
• AnalyticsIndiaMag上的文章：This Developer Ditched Windsurf, Cursor Using Claude with MCPs

社区

加入我们的 Discord服务器 以获得帮助、分享反馈并与其他用户交流。

用户评价

贡献

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

我们欢迎社区的贡献！无论你是发现了一个bug、有一个功能请求还是想贡献代码，以下是你可以提供帮助的方式：

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

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

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

常见问题解答

以下是一些常见问题的答案。如需更全面的FAQ，请参阅我们的 详细FAQ文档。

什么是Claude桌面指挥官？

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

这与Cursor/Windsurf有什么不同？

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

是否需要支付API信用费用？

不需要。这个工具与Claude桌面的标准Pro订阅（每月20美元）配合使用，而不是通过API调用，因此除了订阅费用外，不会产生额外费用。

桌面指挥官会自动更新吗？

是的，当通过npx或Smithery安装时，桌面指挥官会在你重启Claude时自动更新到最新版本。

最常见的用例有哪些？

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

安装或使用工具有困难，在哪里可以获得帮助？

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

数据收集

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

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

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

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

📄 许可证

本项目采用MIT许可证。