Desktop Commander MCP

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

处理代码和文本、运行进程、自动化任务，功能远超其他 AI 编辑器——同时使用宿主客户端订阅，而非 API 令牌费用。

🖥️ 试用 Desktop Commander 应用（测试版）

想要更好的体验？ Desktop Commander 应用提供 MCP 服务器的全部功能，此外还有：

• 使用任意 AI 模型 — Claude、GPT-4.5、Gemini 2.5，或您偏好的任何模型

• 实时查看文件更改 — AI 编辑文件时提供可视化文件预览

• 添加自定义 MCP 和上下文 — 使用您自己的工具进行扩展，无需配置文件

• 即将推出 — 技能系统、听写、后台定时任务等

👉 下载应用（macOS 和 Windows）

下面的 MCP 服务器仍然可以很好地与 Claude Desktop 及其他 MCP 客户端配合使用——该应用是专为那些想要更专业、更精致体验的用户准备的。

Related MCP server: TermPipe MCP

目录

• 功能特性

• 如何安装

• 快速开始

• 使用方法

• 文件预览界面和 Markdown 编辑器

• 处理长时间运行的命令

• 进行中的工作和待办事项

• 赞助商和支持者

• 网站

• 媒体

• 用户评价

• 常见问题

• 参与贡献

• 许可证

您所有的 AI 开发工具，尽在一处。 Desktop Commander 将所有开发工具整合到一个聊天中。 通过模型上下文协议（MCP）在您的计算机上执行长时间运行的终端命令并管理进程。基于 MCP Filesystem Server 构建，提供额外的搜索和替换文件编辑功能。

功能特性

• 远程 AI 控制 - 通过 Remote MCP 从 ChatGPT、Claude 网页版及其他 AI 服务使用 Desktop Commander

• 文件预览界面 - 在 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

  • 详细的时间戳和参数

• 安全护栏（非沙箱——请参阅 SECURITY.md）：

  • 文件操作时防止符号链接遍历

  • 命令阻止列表，防止意外执行

  • Docker 隔离 实现完全隔离

如何安装

在 Claude Desktop 中安装

Desktop Commander 为 Claude Desktop 提供多种安装方式。

📋 更新和卸载信息： 选项 1、2、3、4 和 6 支持自动更新。选项 5 需要手动更新。详情请见下文。

只需在终端中运行：

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

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

此脚本会自动处理所有依赖项和配置。

✅ 自动更新： 是
🔄 手动更新： 重新运行上面的 bash 安装命令
🗑️ 卸载： 运行 npx @wonderwhy-er/desktop-commander@latest remove

1. 访问： https://smithery.ai/server/@wonderwhy-er/desktop-commander

2. 登录 Smithery（如果尚未登录）

3. 在右侧选择您的客户端（Claude Desktop）

4. 使用选择客户端后显示的密钥进行安装

5. 重启 Claude Desktop

✅ 自动更新： 是 - 重启 Claude 时自动更新
🔄 手动更新： 访问 Smithery 页面并重新安装

将此条目添加到您的 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 中删除该条目

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 服务器条目

适合需要隔离或未安装 Node.js 的用户。在带持久化工作环境的沙箱 Docker 容器中运行。

先决条件： 已安装并运行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 持久化： 您的工具、配置、工作文件和包缓存都会在重启后保留。

基本设置（无文件访问）：

{
  "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"
      ]
    }
  }
}

macOS/Linux：

# Check status
bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh) --status

# Reset all persistent data
bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh) --reset

Windows PowerShell：

# Check status
$script = (New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.ps1'); & ([ScriptBlock]::Create("$script")) -Status

# Reset all data
$script = (New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.ps1'); & ([ScriptBlock]::Create("$script")) -Reset

# Show help
$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 配置文件中：

在目录中查看 MCP 服务器

或者手动添加到 ~/.cursor/mcp.json（全局）或项目文件夹中的 .cursor/mcp.json（项目级）。

更多信息请参阅 Cursor MCP 文档。

添加到 ~/.codeium/windsurf/mcp_config.json。更多信息请参阅 Windsurf MCP 文档。

添加到项目中的 .vscode/mcp.json 或 VS Code 用户设置（JSON）。确保在"聊天" > "MCP"下启用了 MCP。可在 Agent 模式下使用。

更多信息请参阅 VS Code MCP 文档。

通过 VS Code 中的 Cline 扩展设置进行配置。打开 Cline 侧边栏，单击 MCP 服务器图标，然后添加上面的 JSON 配置。更多信息请参阅 Cline MCP 文档。

添加到您的 Roo Code MCP 配置文件中。更多信息请参阅 Roo Code MCP 文档。

claude mcp add --scope user desktop-commander -- npx -y @wonderwhy-er/desktop-commander@latest

删除 --scope user 可仅为当前项目安装。更多信息请参阅 Claude Code MCP 文档。

使用"手动添加"功能并粘贴上面的 JSON 配置。更多信息请参阅 Trae MCP 文档。

导航到 Kiro > MCP Servers，点击 + Add，然后粘贴上面的 JSON 配置。更多信息请参阅 Kiro MCP 文档。

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 文档。

在 JetBrains IDE 中，进入 Settings → Tools → AI Assistant → Model Context Protocol (MCP)，点击 + Add，选择 As JSON，然后粘贴上面的 JSON 配置。更多信息请参阅 JetBrains MCP 文档。

添加到 ~/.gemini/settings.json：

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

更多信息请参阅 Gemini CLI 文档。

按下 Cmd/Ctrl+Shift+P，打开 Augment 面板，添加一个名为 desktop-commander 的新 MCP 服务器，并粘贴上面的 JSON 配置。更多信息请参阅 Augment Code MCP 文档。

运行以下命令来添加 Desktop Commander：

qwen mcp add desktop-commander -- npx -y @wonderwhy-er/desktop-commander@latest

或者添加到 .qwen/settings.json（项目级）或 ~/.qwen/settings.json（全局）。更多信息请参阅 Qwen Code MCP 文档。

通过远程 MCP 从 ChatGPT、Claude 网页版 以及其他 AI 服务使用 Desktop Commander——无需桌面应用。

👉 在 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

• 🔍 探索和理解代码库

• 🤖 运行交互式开发环境

使用方法

该服务器提供了一套全面的工具，分为几个类别：

可用工具

快速示例

数据分析：

"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. 字符级差异：使用 {-移除-}{+新增+} 格式精确显示差异内容

4. 多重匹配支持：可通过 expected_replacements 参数替换多个匹配项

5. 全面日志记录：所有模糊搜索操作都会记录日志，便于分析和调试

当搜索失败时，您将看到最接近匹配项的详细信息，包括相似度百分比、执行时间和字符差异。所有这些详细信息都会自动记录到日志中，供后续使用模糊搜索日志工具进行分析。

Docker 支持

🐳 隔离环境使用

Desktop Commander 可以在 Docker 容器中运行，与主机系统完全隔离，对您的计算机零风险。这非常适合测试、开发或需要完全沙箱环境的场景。

安装说明

1. 安装 Docker for Windows/Mac

   • 从 docker.com 下载并安装 Docker Desktop

2. 获取 Desktop Commander Docker 配置

   • 访问：https://hub.docker.com/mcp/server/desktop-commander/manual

   • 选项 A： 使用提供的终端命令进行自动化设置

   • 选项 B： 点击"独立版"获取配置 JSON，并手动添加到您的 Claude Desktop 配置中

3. 挂载您的机器文件夹（即将推出）

   • 关于如何将本地目录挂载到 Docker 容器中的说明即将提供

   • 这将允许您在保持完全隔离的同时处理您的文件

Docker 使用的优势

• 与主机系统完全隔离

• 跨机器的一致环境

• 易于清理 - 完成后只需移除容器即可

• 非常适合测试新功能或配置

URL 支持

• read_file 现在可以同时获取本地文件和 URL 的内容

• 示例：使用 isUrl: true 参数从网络资源读取内容

• 支持处理来自远程来源的文本和图像内容

• 来自 URL 的图像（或本地图像）会以可视化方式显示在 Claude 的界面中，而非纯文本形式

• Claude 可以查看并分析实际的图像内容

• URL 请求的默认超时时间为 30 秒

文件预览界面与 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 环境之外分析日志：

# View recent fuzzy search logs
npm run logs:view -- --count 20

# Analyze patterns and performance
npm run logs:analyze -- --threshold 0.8

# Export logs to CSV or JSON
npm run logs:export -- --format json --output analysis.json

# Clear all logs (with confirmation)
npm run logs:clear

有关这些脚本的详细文档，请参阅 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 如何与您的系统交互。

处理长时间运行的命令

对于可能需要较长时间的命令：

配置管理

⚠️ 重要安全警告

有关全面的安全信息和漏洞报告：请参阅 SECURITY.md

1. 已知安全限制：目录限制和命令阻止可以通过多种方法绕过，包括符号链接、命令替换以及绝对路径或代码执行

2. 始终在单独的聊天窗口中更改配置，与您实际工作的窗口分开。当 Claude 遇到文件系统访问限制时，它有时可能会尝试修改配置设置（如 allowedDirectories）。

3. allowedDirectories 设置目前仅限制文件系统操作，不限制终端命令。终端命令仍然可以访问允许目录之外的文件。

4. 对于生产环境安全：请使用 Docker 安装，它提供与主机系统的完全隔离。

配置工具

您可以使用提供的工具管理服务器配置：

// 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 会浪费令牌：AI 可能不会在文件中进行两次小编辑，而是决定重写整个文件。我们试图强制 AI 以较小的更改进行操作，因为这样可以节省时间和令牌

• 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 行为并避免令牌浪费

• 当超过限制时，系统会自动建议分块处理

• 较小的块意味着当 Claude 达到消息限制时丢失的工作更少

最佳实践

1. 为配置更改创建专用聊天：在一个聊天中完成所有配置更改，然后为您的实际工作开启一个新的聊天。

2. 小心空的 allowedDirectories：将其设置为空数组（[]）将授予对整个文件系统的文件操作访问权限。

3. 使用具体路径：不要使用像 / 这样的宽泛路径，请指定您想要访问的确切目录。

4. 更改后始终验证配置：使用 get_config({}) 确认您的更改已正确应用。

命令行选项

Desktop Commander 支持多个命令行选项以自定义行为：

禁用引导

默认情况下，Desktop Commander 会向新用户（工具调用次数少于 10 次的用户）显示有用的引导提示。您可以通过以下方式禁用此行为：

# Disable onboarding for this session
node dist/index.js --no-onboarding

# Or if using npm scripts
npm run start:no-onboarding

# For npx installations, modify your 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. 使用 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. 启用 Node.js 检查器协议，使用 --inspect-brk=9229 标志

3. 在启动时暂停执行，直到调试器连接

4. 启用额外的调试环境变量

要连接调试器：

• 在 Chrome 中，访问 chrome://inspect 并查找 Node.js 实例

• 在 VS Code 中，使用“附加到 Node 进程”调试配置

• 其他 IDE/工具可能也有类似的 Node.js 调试“附加”选项

重要调试说明：

• 服务器将在启动时暂停，直到调试器连接（由于 --inspect-brk 标志）

• 如果调试期间没有看到活动，请确保已连接到正确的 Node.js 进程

• 可能有多个 Node 进程在运行；请连接到端口 9229 上的那个

• 调试服务器在 Claude 的 MCP 服务器列表中标识为“desktop-commander-debug”

故障排除：

• 如果 Claude 在尝试使用调试服务器时超时，则您的调试器可能未正确连接

• 正确连接后，进程将在命中第一个断点后继续执行

• 连接后，您可以在 IDE 中添加其他断点

模型上下文协议集成

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

• 在 Claude Desktop 中支持本地服务器

• 完整的系统命令执行

• 进程管理

• 文件操作

• 使用搜索/替换块进行代码编辑

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

支持 Desktop Commander

❤️ 支持者名人堂

慷慨的支持者在此展示。感谢您帮助使这个项目成为可能！

网站

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

媒体

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

文章

Claude with MCPs replaced Cursor & Windsurf. How did that happen? - 详细探讨了具有模型上下文协议功能的 Claude 如何改变开发者工作流程。

视频

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

在 AnalyticsIndiaMag 上的出版物

这位开发者使用 Claude with MCPs 抛弃了 Windsurf 和 Cursor

社区

加入我们的 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/DesktopCommanderMCP/issues 打开一个问题

• 有功能想法？ 在问题部分提交功能请求

• 想贡献代码？ 分叉仓库，创建一个分支，并提交拉取请求

• 有问题或讨论？ 在 GitHub Discussions 选项卡中开始讨论

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

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

常见问题解答

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

什么是 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 服务器 获取社区支持，查看 GitHub issues 了解已知问题，或查看 完整 FAQ 获取故障排除提示。您也可以访问我们的 网站 FAQ 部分 获得更友好的体验。如果您遇到新问题，请考虑 打开一个 GitHub issue 并提供有关您问题的详细信息。

如何报告安全漏洞？

请创建一个 GitHub Issue，提供您发现的任何安全漏洞的详细信息。请参阅我们的 安全政策 了解负责任披露的完整指南。

数据收集与隐私

Desktop Commander 收集有限的、伪匿名的遥测数据以改进工具。我们不收集文件内容、文件路径或命令参数。

选择退出： 让 Claude“禁用 Desktop Commander 遥测”或在您的配置中设置 "telemetryEnabled": false。

有关完整详情，请参阅我们的 隐私政策。

验证

许可证

MIT