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許可證。