wonderwhy-er/DesktopCommanderMCP

# Desktop Commander MCP ### 使用 AI 搜索、更新、管理文件并运行终端命令 [](https://www.npmjs.com/package/@wonderwhy-er/desktop-commander) [](https://agentaudit.dev/skills/desktop-commander) [](https://archestra.ai/mcp-catalog/wonderwhy-er__desktopcommandermcp) [](https://smithery.ai/server/@wonderwhy-er/desktop-commander) [](https://www.buymeacoffee.com/wonderwhyer) [](https://discord.gg/kQ27sNnZr7) 处理代码和文本、运行进程并自动化任务，功能远超其他 AI 编辑器——同时使用主机客户端订阅而不是 API Token 费用。 ## 🖥️ 试用 Desktop Commander 应用程序 (Beta) **想要更好的体验？** Desktop Commander 应用程序不仅包含 MCP 服务器的所有功能，还提供： - **使用任何 AI 模型** — Claude、GPT-4.5、Gemini 2.5 或您偏好的任何模型 - **实时查看文件更改** — 在 AI 编辑您的文件时提供可视化文件预览 - **添加自定义 MCP 和上下文** — 使用您自己的工具进行扩展，无需配置文件 - **即将推出** — 技能系统、听写、后台计划任务等 **👉 [下载应用程序](https://desktopcommander.app/#download)** (macOS 和 Windows) ## 目录 - [功能](#features) - [如何安装](#how-to-install) - [入门指南](#getting-started) - [用法](#usage) - [文件预览 UI 和 Markdown 编辑器](#file-preview-ui--markdown-editor) - [处理长时间运行的命令](#handling-long-running-commands) - [进行中的工作和待办事项](#roadmap) - [赞助者和支持者](#support-desktop-commander) - [网站](#website) - [媒体](#media) - [用户评价](#testimonials) - [常见问题](#frequently-asked-questions) - [贡献](#contributing) - [许可证](#license) 将您的所有 AI 开发工具集中在一个地方。 Desktop Commander 将所有开发工具整合到一个聊天界面中。 通过模型上下文协议 (MCP) 在您的计算机上执行长时间运行的终端命令并管理进程。基于 [MCP Filesystem Server](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem) 构建，以提供额外的搜索和替换文件编辑功能。 ## 功能 - **远程 AI 控制** - 通过 [远程 MCP](https://mcp.desktopcommander.app) 从 ChatGPT、Claude 网页版和其他 AI 服务使用 Desktop Commander - **文件预览 UI** - 在 Claude Desktop 中提供可视化文件预览，支持渲染 Markdown、内联图像、可展开内容、内置 Markdown 编辑器以及快捷的“在文件夹中打开”访问 - **增强的终端命令与交互式进程控制** - **在内存中执行代码 (Python, Node.js, R) 而无需保存文件** - **即时数据分析** - 只需请求即可分析 CSV/JSON/Excel 文件 - **原生 Excel 文件支持** - 无需外部工具即可读取、写入、编辑和搜索 Excel 文件 (.xlsx, .xls, .xlsm) - **PDF 支持** - 提取文本读取 PDF、从 Markdown 创建新 PDF、修改现有 PDF - **DOCX 支持** - 通过精准的 XML 编辑和 Markdown 转 DOCX 功能来读取、创建、编辑和搜索 Word 文档 (.docx) - **与正在运行的进程进行交互 (SSH、数据库、开发服务器)** - 执行终端命令并支持输出流式传输 - 支持命令超时和后台执行 - 进程管理（列出和终止进程） - 为长时间运行的命令提供会话管理 - **进程输出分页** - 使用偏移量/长度控制读取终端输出，以防止上下文溢出 - 服务器配置管理： - 获取/设置配置值 - 一次更新多个设置 - 无需重启服务器即可动态更改配置 - 完整的文件系统操作： - 读取/写入文件（文本、Excel、PDF、DOCX） - 创建/列出目录 - **递归目录列表**，具有可配置的深度，并为大型文件夹提供上下文溢出保护 - 移动文件/目录 - 搜索文件和内容（包括 Excel 内容） - 获取文件元数据 - **负向偏移量文件读取**：使用负偏移值从文件末尾开始读取（类似于 Unix 的 tail 命令） - 代码编辑功能： - 针对微小更改的精准文本替换 - 针对重大更改的完整文件重写 - 支持多文件操作 - 基于模式的替换 - 在文件夹中进行基于 vscode-ripgrep 的递归代码或文本搜索 - 全面的审计日志记录： - 所有工具调用都会被自动记录 - 日志轮换大小限制为 10MB - 包含详细的时间戳和参数 - 安全强化： - 在文件操作中防止符号链接遍历 - 带有绕过保护的命令黑名单 - 用于实现完整沙盒化的 [Docker 隔离](#option-6-docker-installation--auto-updates-no-nodejs-required) - 详情请参阅 [SECURITY.md](SECURITY.md) ## 如何安装 ### 在 Claude Desktop 中安装 Desktop Commander 为 Claude Desktop 提供了多种安装方法。

选项 1：通过 npx 安装 ⭐ 自动更新（需要 Node.js）

只需在终端中运行： ``` npx @wonderwhy-er/desktop-commander@latest setup ``` 用于调试模式（允许连接 Node.js 检查器）： ``` npx @wonderwhy-er/desktop-commander@latest setup --debug ``` **设置过程中的命令行选项：** - `--debug`：启用 Node.js 检查器的调试模式 - `--no-onboarding`：禁用新用户的引导提示 如果 Claude 正在运行，请将其重启。 **✅ 自动更新：** 是 - 在您重启 Claude 时会自动更新 **🔄 手动更新：** 再次运行设置命令 **🗑️ 卸载：** 运行 `npx @wonderwhy-er/desktop-commander@latest remove`

选项 2：使用 bash 脚本安装程序 ⭐ 自动更新（需要 Node.js）

``` curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install.sh | bash ``` 此脚本会自动处理所有依赖项和配置。 **✅ 自动更新：** 是 **🔄 手动更新：** 重新运行上面的 bash 安装程序命令 **🗑️ 卸载：** 运行 `npx @wonderwhy-er/desktop-commander@latest remove`

选项 3：通过 Smithery 安装 ⭐ 自动更新（需要 Node.js）

1. **访问：** https://smithery.ai/server/@wonderwhy-er/desktop-commander 2. **登录 Smithery**（如果您还没有账户） 3. **在右侧选择您的客户端** (Claude Desktop) 4. **使用选择客户端后出现的提供的密钥进行安装** 5. **重启 Claude Desktop** **✅ 自动更新：** 是 - 在您重启 Claude 时会自动更新 **🔄 手动更新：** 访问 Smithery 页面并重新安装

选项 4：手动添加到 claude_desktop_config ⭐ 自动更新（需要 Node.js）

将此条目添加到您的 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@latest" ] } } } ``` 如果 Claude 正在运行，请将其重启。 **✅ 自动更新：** 是 - 在您重启 Claude 时会自动更新 **🔄 手动更新：** 再次运行设置命令 **🗑️ 卸载：** 运行 `npx @wonderwhy-er/desktop-commander@latest remove` 或从您的 claude_desktop_config.json 中移除该条目

选项 5：本地检出 ❌ 手动更新（需要 Node.js）

``` git clone https://github.com/wonderwhy-er/DesktopCommanderMCP.git cd DesktopCommanderMCP npm run setup ``` 如果 Claude 正在运行，请将其重启。 设置命令将会安装依赖项、构建服务器并配置 Claude 的桌面应用程序。 **❌ 自动更新：** 否 - 需要手动通过 git 更新 **🔄 手动更新：** `cd DesktopCommanderMCP && git pull && npm run setup` **🗑️ 卸载：** 运行 `npx @wonderwhy-er/desktop-commander@latest remove` 或移除克隆的目录以及 Claude 配置中的 MCP 服务器条目

选项 6：Docker 安装 🐳 ⭐ 自动更新（不需要 Node.js）

非常适合想要隔离环境或没有安装 Node.js 的用户。在沙盒化的 Docker 容器中运行，并提供持久的工作环境。 **前提条件：** 已安装并**正在运行** [Docker Desktop](https://www.docker.com/products/docker-desktop/)，并且已安装 Claude Desktop 应用程序。 **macOS/Linux：** ``` bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh) ``` **Windows PowerShell：** ``` iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.ps1')) ``` 安装程序将检查 Docker、拉取镜像、提示文件夹挂载并配置 Claude Desktop。 **Docker 持久化：** 您的工具、配置、工作文件和包缓存在重启后都会保留。

手动 Docker 配置

**基本设置（无文件访问权限）：** ``` { "mcpServers": { "desktop-commander-in-docker": { "command": "docker", "args": ["run", "-i", "--rm", "mcp/desktop-commander:latest"] } } } ``` **带文件夹挂载：** ``` { "mcpServers": { "desktop-commander-in-docker": { "command": "docker", "args": [ "run", "-i", "--rm", "-v", "/Users/username/Desktop:/mnt/desktop", "-v", "/Users/username/Documents:/mnt/documents", "mcp/desktop-commander:latest" ] } } } ``` **高级文件夹挂载：** ``` { "mcpServers": { "desktop-commander-in-docker": { "command": "docker", "args": [ "run", "-i", "--rm", "-v", "dc-system:/usr", "-v", "dc-home:/root", "-v", "dc-workspace:/workspace", "-v", "dc-packages:/var", "-v", "/Users/username/Projects:/mnt/Projects", "-v", "/Users/username/Downloads:/mnt/Downloads", "mcp/desktop-commander:latest" ] } } } ```

Docker 管理命令

**macOS/Linux：** ``` # 检查状态 bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh) --status # 重置所有持久化数据 bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh) --reset ``` **Windows PowerShell：** ``` # 检查状态 $script = (New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.ps1'); & ([ScriptBlock]::Create("$script")) -Status # 重置所有数据 $script = (New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.ps1'); & ([ScriptBlock]::Create("$script")) -Reset # 显示帮助 $script = (New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.ps1'); & ([ScriptBlock]::Create("$script")) -Help ``` **故障排除：** 重置并从头开始重新安装： ``` bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh) --reset && bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh) ```

**✅ 自动更新：** 是 - `latest` 标签会自动获取较新版本 **🔄 手动更新：** `docker pull mcp/desktop-commander:latest` 然后重启 Claude

### 在其他客户端中安装 Desktop Commander 可与任何兼容 MCP 的客户端配合使用。标准的 JSON 配置如下： ``` { "mcpServers": { "desktop-commander": { "command": "npx", "args": ["-y", "@wonderwhy-er/desktop-commander@latest"] } } } ``` 将此添加到您客户端的 MCP 配置文件中的以下位置：

Cursor

[在 Cursor 中安装 MCP 服务器](https://cursor.directory/mcp/desktop-commander-mcp) 或者手动添加到 `~/.cursor/mcp.json`（全局）或项目文件夹中的 `.cursor/mcp.json`（项目特定）。 详情请参阅 [Cursor MCP 文档](https://docs.cursor.com/context/model-context-protocol)。

Windsurf

添加到 `~/.codeium/windsurf/mcp_config.json`。详情请参阅 [Windsurf MCP 文档](https://docs.windsurf.com/windsurf/cascade/mcp)。

VS Code / GitHub Copilot

添加到您项目中的 `.vscode/mcp.json` 或 VS Code 用户设置 (JSON)。确保在 Chat > MCP 下启用了 MCP。在 Agent 模式下可用。 详情请参阅 [VS Code MCP 文档](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)。

Cline

通过 VS Code 中的 Cline 扩展设置进行配置。打开 Cline 侧边栏，点击 MCP 服务器图标，然后添加上面的 JSON 配置。详情请参阅 [Cline MCP 文档](https://docs.cline.bot/mcp/configuring-mcp-servers)。

Roo Code

添加到您的 Roo Code MCP 配置文件。详情请参阅 [Roo Code MCP 文档](https://docs.roocode.com/features/mcp/using-mcp-in-roo)。

Claude Code

``` claude mcp add --scope user desktop-commander -- npx -y @wonderwhy-er/desktop-commander@latest ``` 移除 `--scope user` 以便仅为当前项目安装。详情请参阅 [Claude Code MCP 文档](https://docs.anthropic.com/en/docs/claude-code/mcp)。

Trae

使用“手动添加”功能并粘贴上面的 JSON 配置。详情请参阅 [Trae MCP 文档](https://docs.trae.ai/ide/model-context-protocol?_lang=en)。

Kiro

导航到 `Kiro` > `MCP Servers`，点击 `+ Add`，然后粘贴上面的 JSON 配置。详情请参阅 [Kiro MCP 文档](https://kiro.dev/docs/mcp/configuration/)。

Codex (OpenAI)

Codex 使用 TOML 配置。运行此命令以添加 Desktop Commander： ``` codex mcp add desktop-commander -- npx -y @wonderwhy-er/desktop-commander@latest ``` 或者手动添加到 `~/.codex/config.toml`： ``` [mcp_servers.desktop-commander] command = "npx" args = ["-y", "@wonderwhy-er/desktop-commander@latest"] ``` 详情请参阅 [Codex MCP 文档](https://developers.openai.com/codex/mcp/)。

JetBrains (AI Assistantb>

在 JetBrains IDE 中，前往 **Settings → Tools → AI Assistant → Model Context Protocol (MCP)**，点击 `+` Add，选择 **As JSON**，然后粘贴上面的 JSON 配置。详情请参阅 [JetBrains MCP 文档](https://www.jetbrains.com/help/ai-assistant/configure-an-mcp-server.html)。

Gemini CLI

添加到 `~/.gemini/settings.json`： ``` { "mcpServers": { "desktop-commander": { "command": "npx", "args": ["-y", "@wonderwhy-er/desktop-commander@latest"] } } } ``` 详情请参阅 [Gemini CLI 文档](https://github.com/google-gemini/gemini-cli)。

Augment Code

按 `Cmd/Ctrl+Shift+P`，打开 Augment 面板，然后添加一个名为 `desktop-commander` 的新 MCP 服务器并使用上面的 JSON 配置。详情请参阅 [Augment Code MCP 文档](https://docs.augmentcode.com/setup-augment/mcp)。

Qwen Code

运行此命令以添加 Desktop Commander： ``` qwen mcp add desktop-commander -- npx -y @wonderwhy-er/desktop-commander@latest ``` 或者添加到 `.qwen/settings.json`（项目）或 `~/.qwen/settings.json`（全局）。详情请参阅 [Qwen Code MCP 文档](https://qwenlm.github.io/qwen-code-docs/en/developers/tools/mcp-server/)。

ChatGPT / Claude Web (Remote MCP)

通过 Remote MCP 从 **ChatGPT**、**Claude Web** 和其他 AI 服务使用 Desktop Commander —— 无需桌面应用程序。 **👉 [从 mcp.desktopcommander.app 开始](https://mcp.desktopcommander.app)** 工作原理： 1. 您在计算机上运行一个轻量级的 **Remote Device** 2. 它安全地连接到云端的 Remote MCP 服务 3. 您的 AI 通过云向您设备发送命令 4. 命令在本地执行，结果返回给您的 AI 5. **您保持控制权** —— 随时可以通过 `Ctrl+C` 停止 ### 安全性 - ✅ 设备只有在您启动它时才会运行 - ✅ 命令在您的用户权限下执行 - ✅ 安全的 OAuth 身份验证和加密通信通道

## 更新和卸载 Desktop Commander ### 自动更新（选项 1、2、3、4 和 6） **选项 1 (npx)、选项 2 (bash 安装程序)、3 (Smithery)、4 (手动配置) 和 6 (Docker)** 会在您每次重启 Claude 时自动更新到最新版本。无需手动干预。 ### 手动更新（选项 5） - **选项 5（本地检出）：** `cd DesktopCommanderMCP && git pull && npm run setup` ### 卸载 Desktop Commander #### 🤖 自动卸载（推荐） 完全移除 Desktop Commander 的最简单方法： ``` npx @wonderwhy-er/desktop-commander@latest remove ``` 此自动卸载程序将会： - ✅ 从 Claude 的 MCP 服务器配置中移除 Desktop Commander - ✅ 在进行更改之前创建您的 Claude 配置备份 - ✅ 为彻底移除提供指导 - ✅ 如果出现任何问题，可从备份还原 #### 🔧 手动卸载 如果自动卸载程序不起作用或者您偏好手动移除： ##### 从 Claude 配置中移除 1. **找到您的 Claude Desktop 配置文件：** - **macOS：** `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows：** `%APPDATA%\Claude\claude_desktop_config.json` - **Linux：** `~/.config/Claude/claude_desktop_config.json` 2. **编辑配置文件：** - 在文本编辑器中打开该文件 - 找到并移除 `"mcpServers"` 部分中的 `"desktop-commander"` 条目 - 保存文件 **示例 - 移除此部分：** ``` { "desktop-commander": { "command": "npx", "args": ["@wonderwhy-er/desktop-commander@latest"] } } ``` 关闭并重启 Claude Desktop 以完成移除。 #### 🆘 故障排除 **如果自动卸载失败：** - 使用手动卸载作为后备方案 **如果卸载后 Claude 无法启动：** - 还原由卸载程序创建的备份配置文件 - 或者手动修复您的 claude_desktop_config.json 中的 JSON 语法 **需要帮助？** - 加入我们的 Discord 社区：https://discord.com/invite/kQ27sNnZr7 ## 入门指南 安装 Desktop Commander 并重启 Claude Desktop 后，您就可以开始升级您的 Claude 体验了！ ### 🚀 新用户引导 Desktop Commander 包含智能引导功能，帮助您发现它的可能性： **对于新用户：** 当您刚刚开始使用时（成功执行的命令少于 10 个），Claude 会在您成功使用 Desktop Commander 后自动提供有用的入门指导和实用教程。 **随时请求帮助：** 您只需这样说，即可随时请求引导协助： - *“帮我开始使用 Desktop Commander”* - *“给我展示一些 Desktop Commander 的示例”* - *“我可以用 Desktop Commander 做什么？”* Claude 随后会向您展示适合初学者的教程和示例，包括： - 📁 自动整理您的 Downloads 文件夹 - 📊 使用 Python 分析 CSV/Excel 文件 - ⚙️ 设置 GitHub Actions CI/CD - 🔍 探索和理解代码库 - 🤖 运行交互式开发环境 ## 用法 该服务器提供了一套全面的工具，分为几个类别： ### 可用工具 | 类别 | 工具 | 描述 | |----------|------|-------------| | **配置** | `get_config` | 获取完整的服务器配置 JSON（包括 blockedCommands、defaultShell、allowedDirectories、fileReadLineLimit、fileWriteLineLimit、telemetryEnabled） | | | `set_config_value` | 通过键设置特定的配置值。可用设置：
• `blockedCommands`：无法执行的 Shell 命令数组
• `defaultShell`：用于命令的 Shell（例如 bash、zsh、powershell）
• `allowedDirectories`：服务器可以访问以进行文件操作的文件系统路径数组（⚠️ 终端命令仍然可以访问这些目录之外的文件）
• `fileReadLineLimit`：一次读取的最大行数（默认值：1000）
• `fileWriteLineLimit`：一次写入的最大行数（默认值：50）
• `telemetryEnabled`：启用/禁用遥测（布尔值） | | **终端** | `start_process` | 启动程序，并智能检测程序何时准备好接收输入 | | | `interact_with_process` | 向运行中的程序发送命令并获取响应 | | | `read_process_output` | 读取运行中进程的输出 | | | `force_terminate` | 强制终止正在运行的终端会话 | | | `list_sessions` | 列出所有活动的终端会话 | | | `list_processes` | 列出所有正在运行的进程及其详细信息 | | | `kill_process` | 通过 PID 终止正在运行的进程 | | **文件系统** | `read_file` | 读取本地文件系统、URL、Excel 文件 (.xlsx, .xls, .xlsm) 和 PDF 的内容，支持基于行/页的分页 | | | `read_multiple_files` | 同时读取多个文件 | | | `write_file` | 写入文件内容，支持重写或追加模式。支持 Excel 文件（JSON 2D 数组格式）。对于 PDF，请使用 `write_pdf` | | | `write_pdf` | 从 Markdown 创建新 PDF 文件或修改现有 PDF（插入/删除页面）。支持 HTML/CSS 样式和 SVG 图形 | | | `create_directory` | 创建新目录或确保目录存在 | | | `list_directory` | 获取文件和目录的详细递归列表（支持深度参数，默认深度=2） | | | `move_file` | 移动或重命名文件和目录 | | | `start_search` | 启动流式搜索，按名称或内容模式查找文件（搜索文本文件和 Excel 内容） | | | `get_more_search_results` | 从活动搜索中获取支持偏移量的分页结果 | | | `stop_search` | 优雅地停止活动搜索 | | | `list_searches` | 列出所有活动的搜索会话 | | | `get_file_info` | 检索有关文件或目录的详细元数据（包括 Excel 文件的工作表信息） | | **文本编辑** | `edit_block` | 对文本文件应用有针对性的文本替换，或对 Excel 文件进行基于范围的单元格更新 | | **分析** | `get_usage_stats` | 获取使用统计数据供您自己分析 | | | `get_recent_tool_calls` | 获取最近的工具调用历史记录，包含参数和输出，用于调试和上下文恢复 | | | `give_feedback_to_desktop_commander` | 在浏览器中打开反馈表单，向 Desktop Commander 团队提供反馈 | ### 快速示例 **数据分析：** ``` "Analyze sales.csv and show top customers" → Claude runs Python code in memory ``` **远程访问：** ``` "SSH to my server and check disk space" → Claude maintains SSH session ``` **开发：** ``` "Start Node.js and test this API" → Claude runs interactive Node session ``` ### 工具用法示例 搜索/替换块格式： ``` filepath.ext <<<<<<< SEARCH content to find ======= new content >>>>>>> REPLACE ``` 示例： ``` src/main.js <<<<<<< SEARCH console.log("old message"); ======= console.log("new message"); >>>>>>> REPLACE ``` ### 增强的编辑块功能 `edit_block` 工具包含多项旨在提高可靠性的增强功能： 1. **改进的提示**：工具描述现在强调进行多次小规模、集中的编辑，而不是一次大更改 2. **模糊搜索回退**：当完全匹配失败时，它会执行模糊搜索并提供详细的反馈 3. **字符级别的差异**：使用 `{-removed-}{+added+}` 格式准确显示不同之处 4. **支持多次出现**：可以通过 `expected_replacements` 参数替换多个实例 5. **全面的日志记录**：所有模糊搜索都会被记录下来以供分析和调试 当搜索失败时，您将看到有关找到的最接近匹配的详细信息，包括相似度百分比、执行时间和字符差异。所有这些细节都会被自动记录，以便日后使用模糊搜索日志工具进行分析。 ### Docker 支持 ### 🐳 隔离环境使用 Desktop Commander 可以在 Docker 容器中运行，以实现**与您的主机系统完全隔离**，从而为您的计算机提供**零风险**保障。这非常适合测试、开发，或者当您想要完全沙盒化时使用。 ### 安装说明 1. **安装 Docker for Windows/Mac** - 从 [docker.com](https://www.docker.com/products/docker-desktop/) 下载并安装 Docker Desktop 2. **获取 Desktop Commander Docker 配置** - 访问：https://hub.docker.com/mcp/server/desktop-commander/manual - **选项 A：** 使用提供的终端命令进行自动设置 - **选项 B：** 点击“Standalone”获取配置 JSON，并手动将其添加到您的 Claude Desktop 配置中  3. **挂载您的机器文件夹（即将推出）** - 有关如何将本地目录挂载到 Docker 容器中的说明将很快提供 - 这将允许您在保持完全隔离的同时处理您的文件 ### 使用 Docker 的好处 - 与您的主机系统**完全隔离** - 跨不同机器的**一致环境** - **易于清理** - 完成后只需移除容器即可 - **非常适合测试**新功能或配置 ## URL 支持 - `read_file` 现在可以从本地文件和 URL 获取内容 - 示例：带 `isUrl: true` 参数的 `read_file` 用于从网络资源读取 - 处理来自远程源的文本和图像内容 - 图像（本地或来自 URL）在 Claude 的界面中是以可视化方式显示的，而不是作为文本 - Claude 可以看到并分析实际的图像内容 - URL 请求的默认超时时间为 30 秒 ## 文件预览 UI 和 Markdown 编辑器 Desktop Commander 在 Claude Desktop 中包含一个丰富的文件预览小部件，可以在 AI 处理文件时以可视化方式渲染它们。 ### 支持的文件类型 - **Markdown** — 渲染预览并带有内置编辑器 - **图像** — 内联显示（PNG、JPEG、GIF、WebP 等） - **代码文件** — 带有语法高亮的源代码视图 - **HTML** — 渲染预览，可切换到源代码视图 - **目录** — 可展开/折叠且支持延迟加载的交互式树状结构 - **PDF、Excel、DOCX** — 原生内容提取和显示 ### Markdown 编辑器 在 Claude Desktop 中查看 `.md` 文件时，您可以直接在预览面板中编辑它 —— 无需打开单独的应用程序。 **使用方法：** 1. 要求 Claude 读取或创建一个 Markdown 文件 2. 使用 **⤢ 展开** 按钮将文件预览扩展到全屏 3. 编辑器会在全屏模式下自动激活 4. 使用实时的预览切换、复制、撤销和保存控件来编辑您的内容 5. 更改会保存回磁盘；折叠以返回内联视图 **编辑器功能：** - 实时**编辑 / 预览切换** —— 在原始 Markdown 和渲染输出之间切换 - **自动保存**到磁盘，并带有保存状态指示器 - **撤销**支持以还原未保存的更改 - **复制**按钮以获取完整的 Markdown 源码 - **在编辑器中打开** —— 直接从面板启动您默认的 Markdown 应用程序 - 分文件感知 —— 当文件仅被部分读取时，加载并合并周围的行 - 文本选择上下文 —— 在预览模式中选择文本，AI 可以引用您的选择 ### 目录浏览器 当 Claude 运行 `list_directory` 时，结果会在预览面板中作为交互式文件树打开 —— 而不仅仅是原始文本输出。 **功能：** - **可展开的树** —— 文件夹在点击时展开和折叠；立即显示顶层内容 - **延迟加载** —— 子文件夹按需加载，以保持初始视图快速响应 - **大型目录处理** —— 包含许多项目的目录会显示一个 `⚠ 点击加载全部` 按钮，而不是让视图不堪重负 - **在 Finder/资源管理器中打开** —— 每个文件夹都有一个快速打开按钮，可在您的文件管理器中显示它 - **点击预览** —— 点击树中的任何文件即可直接在文件预览面板中打开它 - **后退导航** —— 从树中打开文件后，← 后退按钮可返回到目录视图 ### 其他预览功能 - **展开 / 折叠** —— 在紧凑的摘要行和完整面板之间切换 - **在文件夹中打开** —— 一键在 Finder/资源管理器中显示文件 - **加载更多行** —— 在部分读取窗口的上方或下方增量加载内容 - **文本选择** —— 在任何预览中高亮显示文本；AI 可以看到并引用您的选择 ## 模糊搜索日志分析 (npm 脚本) 模糊搜索日志系统包含便捷的 npm 脚本，用于在 MCP 环境之外分析日志： ``` # 查看最近的模糊搜索日志 npm run logs:view -- --count 20 # 分析模式和性能 npm run logs:analyze -- --threshold 0.8 # 将日志导出为 CSV 或 JSON npm run logs:export -- --format json --output analysis.json # 清除所有日志（需确认） npm run logs:clear ``` 有关这些脚本的详细文档，请参阅 [scripts/README.md](scripts/README.md)。 ## 模糊搜索日志 Desktop Commander 包含对 `edit_block` 工具中模糊搜索操作的全面日志记录。当未找到完全匹配时，系统会执行模糊搜索并记录详细信息以供分析。 ### 记录的内容 每次模糊搜索操作都会记录： - **搜索和找到的文本**：您要查找的文本与实际找到的文本 - **相似度分数**：匹配的接近程度 (0-100%) - **执行时间**：搜索花费的时间 - **字符差异**：详细差异，准确显示不同之处 - **文件元数据**：扩展名、搜索/找到的文本长度 - **字符代码**：导致差异的特定字符代码 ### 日志位置 日志会自动保存到： - **macOS/Linux**：`~/.claude-server-commander-logs/fuzzy-search.log` - **Windows**：`%USERPROFILE%\.claude-server-commander-logs\fuzzy-search.log` ### 您将了解到的内容 模糊搜索日志可帮助您了解： 1. **为什么完全匹配会失败**：常见问题如空格差异、行尾符或字符编码 2. **性能模式**：搜索复杂性如何影响执行时间 3. **文件类型问题**：哪些文件扩展名通常存在匹配问题 4. **字符编码问题**：导致差异的特定字符代码 ## 审计日志 Desktop Commander 现在包含对所有工具调用的全面日志记录： ### 记录的内容 - 每次工具调用都会记录时间戳、工具名称和参数（出于隐私考虑已进行净化处理） - 日志在达到 10MB 大小时会自动轮换 ### 日志位置 日志保存到： - **macOS/Linux**：`~/.claude-server-commander/claude_tool_call.log` - **Windows**：`%USERPROFILE%\.claude-server-commander\claude_tool_call.log` 此审计跟踪有助于调试、安全监控以及了解 Claude 如何与您的系统进行交互。 ## 处理长时间运行的命令 对于可能需要一段时间的命令： ## 配置管理 ### ⚠️ 重要安全警告 1. **已知的安全限制**：目录限制和命令阻止可以通过各种方法绕过，包括符号链接、命令替换以及绝对路径或代码执行 2. **始终在与您进行实际工作不同的单独聊天窗口中更改配置**。如果遇到文件系统访问限制，Claude 有时可能会尝试修改配置设置（如 `allowedDirectories`）。 3. **`allowedDirectories` 设置目前仅限制文件系统操作**，而不限制终端命令。终端命令仍然可以访问允许目录之外的文件。 4. **对于生产环境的安全性**：请使用 [Docker 安装方式](#option-6-docker-installation-🐳-⭐-auto-updates-no-nodejs-required)，它提供了与主机系统完全的隔离。 ### 配置工具 您可以使用提供的工具来管理服务器配置： ``` // Get the entire config get_config({}) // Set a specific config value set_config_value({ "key": "defaultShell", "value": "/bin/zsh" }) // Set multiple config values using separate calls set_config_value({ "key": "defaultShell", "value": "/bin/bash" }) set_config_value({ "key": "allowedDirectories", "value": ["/Users/username/projects"] }) ``` 配置会保存到服务器工作目录中的 `config.json` 文件，并在服务器重启后持久存在。 #### 了解 fileWriteLineLimit `fileWriteLineLimit` 设置控制在单次 `write_file` 操作中可以写入的行数（默认值：50 行）。存在此限制有几个重要原因： **为什么存在此限制：** - **AI 会在 Token 上造成浪费**：与其在一个文件中进行两处小修改，AI 可能会决定重写整个文件。我们正试图强制 AI 以较小的更改进行操作，因为这能节省时间和 Token - **Claude UX 消息限制**：在一条消息内有限制，点击“继续”并不能真正解决问题。我们在这里试图做的是让 AI 分成较小的块工作，这样当您达到该限制时，多个块已经成功，并且那些工作不会丢失——只需从最后一块重新开始即可 **设置限制：** ``` // You can set it to thousands if you want set_config_value({ "key": "fileWriteLineLimit", "value": 1000 }) // Or keep it smaller to force more efficient behavior set_config_value({ "key": "fileWriteLineLimit", "value": 25 }) ``` **最大值**：如果您愿意，可以将其设置为数千行——没有技术限制。 **最佳实践：** - 保持默认值 (50) 以鼓励高效的 AI 行为并避免 Token 浪费 - 当超出限制时，系统会自动建议分块 - 较小的块意味着当 Claude 达到消息限制时损失的工作量更少 ### 最佳实践 1. **为配置更改创建专用聊天**：在一个聊天中进行所有配置更改，然后开始一个新的聊天进行您的实际工作。 2. **小心空的 `allowedDirectories`**：将其设置为空数组 (`[]`) 将授予对您整个文件系统的文件操作访问权限。 3. **使用特定路径**：不要使用像 `/` 这样的宽泛路径，而应指定您想要访问的确切目录。 4. **更改后始终验证配置**：使用 `get_config({})` 确认您的更改已正确应用。 ## 命令行选项 Desktop Commander 支持多个命令行选项来自定义行为： ### 禁用引导 默认情况下，Desktop Commander 会向新用户（工具调用次数少于 10 次的用户）显示有用的引导提示。您可以禁用此行为： ``` # 为此会话禁用引导 node dist/index.js --no-onboarding # 或者如果使用 npm scripts npm run start:no-onboarding # 对于 npx 安装，请修改您的 claude_desktop_config.json： { "mcpServers": { "desktop-commander": { "command": "npx", "args": [ "-y", "@wonderwhy-er/desktop-commander@latest", "--no-onboarding" ] } } } ``` **何时自动禁用引导：** - 当 MCP 客户端名称设置为“desktop-commander”时 - 当使用 `--no-onboarding` 标志时 - 在用户使用了引导提示或进行了 10 次以上的工具调用之后 **调试信息：** 服务器将记录何时禁用引导：`"Onboarding disabled via --no-onboarding flag"` ## 使用不同的 Shell 您可以指定用于命令执行的 Shell： ``` // Using default shell (bash or system default) execute_command({ "command": "echo $SHELL" }) // Using zsh specifically execute_command({ "command": "echo $SHELL", "shell": "/bin/zsh" }) // Using bash specifically execute_command({ "command": "echo $SHELL", "shell": "/bin/bash" }) ``` 这允许您使用特定于 Shell 的功能或在不同命令之间保持一致的环境。 1. `execute_command` 在超时后返回并附带初始输出 2. 命令在后台继续运行 3. 使用带有 PID 的 `read_output` 获取新输出 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 Filesystem Server，以实现： - Claude Desktop 中的本地服务器支持 - 完整的系统命令执行 - 进程管理 - 文件操作 - 通过搜索/替换块进行代码编辑 作为探索 Claude MCP 的一部分而创建：https://youtube.com/live/TlbjFDbl5Us ## 支持 Desktop Commander

📢 支持本项目

Desktop Commander MCP 是免费且开源的，但需要您的支持才能茁壮成长！

我们的理念很简单：如果您没有获得成功，我们就不希望您为此付费。但如果 Desktop Commander 对您的成功有所贡献，请考虑为我们的成功做出贡献。

支持方式：

• 🌟 GitHub Sponsors - 持续支持
• ☕ Buy Me A Coffee - 单次贡献
• 💖 Patreon - 成为赞助人并每月支持我们
• ⭐ 在 GitHub 上加星 - 帮助其他人发现这个项目

### ❤️ 支持者名人堂 慷慨的支持者将在此处展示。感谢您帮助实现这个项目！

Jon Richards

Matija Stepanic

为什么您的支持很重要

您的支持使我们能够：

• 继续积极的开发和维护
• 添加新功能和集成
• 提高跨平台的兼容性
• 提供更好的文档和示例
• 围绕项目建立更强大的社区

## 网站 访问我们的官方网站 [https://desktopcommander.app/](https://desktopcommander.app/) 获取最新信息、文档和更新。 ## 媒体 通过这些资源了解更多关于此项目的信息： ### 文章 [带有 MCP 的 Claude 取代了 Cursor 和 Windsurf。这是如何发生的？](https://wonderwhy-er.medium.com/claude-with-mcps-replaced-cursor-windsurf-how-did-that-happen-c1d1e2795e96) - 深入探讨带有模型上下文协议功能的 Claude 是如何改变开发者工作流程的。 ### 视频 [Claude Desktop Commander 视频教程](https://www.youtube.com/watch?v=ly3bed99Dy8) - 观看如何有效地设置和使用 Commander。 ### AnalyticsIndiaMag 上的出版物 [ 这位开发者使用带有 MCP 的 Claude 抛弃了 Windsurf 和 Cursor](https://analyticsindiamag.com/ai-features/this-developer-ditched-windsurf-cursor-using-claude-with-mcps/) ### 社区 加入我们的 [Discord 服务器](https://discord.gg/kQ27sNnZr7) 以获取帮助、分享反馈并与其他用户联系。 ## 用户评价 [ https://www.youtube.com/watch?v=ly3bed99Dy8&lc=UgyyBt6_ShdDX_rIOad4AaABAg ](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=UgztdHvDMqTb9jiqnf54AaABAg ) [ https://www.youtube.com/watch?v=ly3bed99Dy8&lc=UgyQFTmYLJ4VBwIlmql4AaABAg](https://www.youtube.com/watch?v=ly3bed99Dy8&lc=UgyQFTmYLJ4VBwIlmql4AaABAg) [ https://www.youtube.com/watch?v=ly3bed99Dy8&lc=Ugy4-exy166_Ma7TH-h4AaABAg](https://www.youtube.com/watch?v=ly3bed99Dy8&lc=Ugy4-exy166_Ma7TH-h4AaABAg) [ https://medium.com/@pharmx/you-sir-are-my-hero-62cff5836a3e](https://medium.com/@pharmx/you-sir-are-my-hero-62cff5836a3e) 如果您觉得这个项目有用，请考虑在 GitHub 上给它一个 ⭐ 星！这有助于其他人发现该项目并鼓励进一步开发。 我们欢迎社区的贡献！无论您是发现了一个 Bug、有功能请求，还是想要贡献代码，您都可以通过以下方式提供帮助： - **发现了 Bug？** 在 [github.com/wonderwhy-er/DesktopCommanderMCP/issues](https://github.com/wonderwhy-er/DesktopCommanderMCP/issues) 提交 issue - **有功能想法？** 在 issues 部分提交功能请求 - **想要贡献代码？** 复刻该存储库，创建一个分支，并提交拉取请求 - **有疑问或讨论？** 在 GitHub Discussions 标签页中发起讨论 所有贡献，无论大小，我们都深表感谢！ 如果您觉得此工具对您的工作流程有价值，请考虑[支持该项目](https://www.buymeacoffee.com/wonderwhyer)。 ## 常见问题 以下是对一些常见问题的解答。有关更全面的常见问题解答，请参阅我们的[详细常见问题文档](FAQ.md)。 ### 什么是 Desktop Commander？ 它是一个 MCP 工具，使 Claude Desktop 能够访问您的文件系统和终端，将 Claude 变成一个用于编码、自动化、代码库探索等方面的多功能助手。 ### 这与 Cursor/Windsurf 有何不同？ 与专注于 IDE 的工具不同，Claude Desktop Commander 提供了一种面向整个操作系统、以解决方案为导向的方法，而不仅仅是在编码环境中工作。Claude 会完整读取文件而不是将其分块，可以同时跨多个项目工作，并且一次性执行更改，无需不断审查。 ### 我需要支付 API 额度费用吗？ 不需要。此工具适用于 Claude Desktop 的标准 Pro 订阅（20 美元/月），而不是 API 调用，因此除了订阅费之外，您不会产生额外费用。 ### Desktop Commander 会自动更新吗？ 是的，当通过 npx 或 Smithery 安装时，Desktop Commander 会在您重启 Claude 时自动更新到最新版本。不需要手动更新过程。 ### 最常见的用例是什么？ - 探索和理解复杂的代码库 - 生成图表和文档 - 跨系统自动化任务 - 同时处理多个项目 - 通过精确控制进行精准的代码更改 ### 我在安装或使用该工具时遇到了问题。我可以在哪里获得帮助？ 加入我们的 [Discord 服务器](https://discord.gg/kQ27sNnZr7) 获取社区支持，查看 [GitHub issues](https://github.com/wonderwhy-er/DesktopCommanderMCP/issues) 了解已知问题，或查看[完整常见问题解答](FAQ.md)获取故障排除提示。您还可以访问我们的[网站常见问题解答部分](https://desktopcommander.app#faq)以获得更友好的用户体验。如果您遇到新问题，请考虑[提交一个 GitHub issue](https://github.com/wonderwhy-er/DesktopCommanderMCP/issues/new)，并附上有关您问题的详细信息。 ### 如何报告安全漏洞？ 请创建一个 [GitHub Issue](https://github.com/wonderwhy-er/DesktopCommanderMCP/issues)，并附上有关您发现的任何安全漏洞的详细信息。有关负责任的披露的完整指南，请参阅我们的[安全政策](SECURITY.md)。 ## 数据收集和隐私 Desktop Commander 收集有限的、 pseudonymous（化名） 遥测数据以改进工具。我们不会收集文件内容、文件路径或命令参数。 **选择退出：** 要求 Claude “禁用 Desktop Commander 遥测”，或者在您的配置中设置 `"telemetryEnabled": false`。 有关完整的详细信息，请参阅我们的[隐私政策](PRIVACY.md)。 ## 验证 [](https://mseep.ai/app/25ff7a06-58bc-40b8-bd79-ebb715140f1a) ## 许可证 MIT