Desktop Commander MCP 详细部署教程

Desktop Commander MCP 是一个强大的工具，让 Claude Desktop 能够控制终端、搜索文件系统并进行文件编辑。本文将详细介绍多种安装部署方法，您可以根据自己的需求选择最合适的方式。

📋 目录

准备工作
安装方法概览
方法一：通过 npx 安装（推荐）
方法二：Bash 脚本安装（macOS）
方法三：Docker 安装（完全隔离）
方法四：手动配置 Claude Desktop
方法五：本地源码安装
在其他 MCP 客户端中安装
配置与管理
更新与卸载
常见问题排查

准备工作

系统要求

操作系统: macOS、Windows 或 Linux
Claude Desktop: 已安装并登录
Node.js: 对于非 Docker 安装方式，需要 Node.js 18+（部分安装方式会自动安装）

验证 Node.js 安装（如需）

1 2	node --version npm --version

如果未安装，请访问 nodejs.org 下载安装。

安装方法概览

方法	自动更新	需要 Node.js	隔离性	推荐场景
npx 安装	✅	✅	❌	大多数用户（推荐）
Bash 脚本	✅	自动安装	❌	macOS 用户
Docker 安装	✅	❌	✅	追求安全隔离
手动配置	✅	✅	❌	熟悉配置文件的用户
本地源码	❌	✅	❌	开发者/贡献者

方法一：通过 npx 安装（推荐）

这是最简单且推荐的安装方式，支持自动更新。

步骤 1：运行安装命令

打开终端，执行以下命令：

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

如需调试模式（允许 Node.js 调试器连接）：

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

可选参数：

--debug: 启用调试模式
--no-onboarding: 禁用新用户引导提示

步骤 2：完成安装

安装脚本会自动：

下载并安装 Desktop Commander
配置 Claude Desktop 的 MCP 设置
提示您完成必要的配置

步骤 3：重启 Claude Desktop

完全退出 Claude Desktop 应用，然后重新打开。

✅ 验证安装

在 Claude 中输入以下内容测试：

1	"帮我查看当前目录下的文件"

如果 Claude 能够列出文件，说明安装成功！

方法二：Bash 脚本安装（macOS）

这种方法会自动安装 Node.js（如果未安装），适合 macOS 用户。

执行安装脚本

在终端中运行：

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

特点

✅ 自动检测并安装 Node.js
✅ 自动配置 Claude Desktop
✅ 支持自动更新

重启 Claude Desktop

安装完成后，重启 Claude Desktop 即可使用。

方法三：Docker 安装（完全隔离）

如果您希望 Desktop Commander 在完全隔离的环境中运行，或不想安装 Node.js，Docker 方式是最佳选择。

前提条件

安装并运行 Docker Desktop
已安装 Claude Desktop

自动安装（推荐）

macOS/Linux:

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

Windows PowerShell:

1	iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.ps1'))

手动 Docker 配置

如果您想手动配置，将以下内容添加到 Claude Desktop 配置文件中：

基础配置（无文件访问）:

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

注意: 将 /Users/username/ 替换为您的实际路径。

Docker 管理命令

macOS/Linux 查看状态:

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

重置所有数据:

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

Docker 的优势

🔒 完全隔离: 与主机系统隔离，更安全
🔄 自动更新: 使用 latest 标签自动获取新版本
📦 持久化数据: 工具、配置和工作文件在容器重启后保留

方法四：手动配置 Claude Desktop

如果您喜欢手动控制，或想了解底层配置，可以手动编辑配置文件。

步骤 1：找到配置文件

macOS:

1	~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

1	%APPDATA%\Claude\claude_desktop_config.json

Linux:

1	~/.config/Claude/claude_desktop_config.json

步骤 2：编辑配置文件

用文本编辑器打开配置文件，添加以下内容：

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

步骤 3：保存并重启

保存文件，完全退出并重新启动 Claude Desktop。

方法五：本地源码安装

适合开发者或需要修改源码的用户。

步骤 1：克隆仓库

1 2	git clone https://github.com/wonderwhy-er/DesktopCommanderMCP.git cd DesktopCommanderMCP

步骤 2：安装依赖并构建

1	npm run setup

这会安装依赖、构建项目并配置 Claude Desktop。

⚠️ 注意

❌ 不支持自动更新
手动更新需要：cd DesktopCommanderMCP && git pull && npm run setup
适合开发和贡献代码

在其他 MCP 客户端中安装

Desktop Commander 支持所有 MCP 兼容客户端。

通用配置

在所有客户端中，您需要添加以下 JSON 配置：

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

各客户端配置位置

客户端	配置文件位置
Cursor	`~/.cursor/mcp.json` 或项目中的 `.cursor/mcp.json`
Windsurf	`~/.codeium/windsurf/mcp_config.json`
VS Code	`.vscode/mcp.json` 或用户设置 JSON
Cline	通过 Cline 扩展的 MCP 服务器设置
Claude Code	`claude mcp add --scope user desktop-commander -- npx -y @wonderwhy-er/desktop-commander@latest`
Codex (OpenAI)	`~/.codex/config.toml`（TOML 格式）
JetBrains	设置 → 工具 → AI Assistant → MCP
Gemini CLI	`~/.gemini/settings.json`
Qwen Code	`qwen mcp add desktop-commander -- npx -y @wonderwhy-er/desktop-commander@latest`

配置与管理

查看配置

在 Claude 中询问：

1	"获取 Desktop Commander 的当前配置"

或使用工具：

1	get_config({})

修改配置

关键配置项：

配置键	说明	示例值
`blockedCommands`	禁止执行的命令列表	`["rm -rf", "shutdown"]`
`defaultShell`	默认使用的 Shell	`/bin/zsh`
`allowedDirectories`	允许访问的目录（仅文件操作）	`["/Users/username/projects"]`
`fileReadLineLimit`	单次读取最大行数	`1000`
`fileWriteLineLimit`	单次写入最大行数	`50`

修改示例:

1 2	"设置 fileWriteLineLimit 为 100" "将默认 Shell 改为 /bin/bash"

⚠️ 安全提示

allowedDirectories 仅限制文件操作，终端命令仍可访问其他目录
建议在单独的对话窗口中修改配置，避免 Claude 在工作时意外修改
生产环境推荐使用 Docker 安装以获得完全隔离

更新与卸载

自动更新

使用 npx、Bash 脚本、Smithery、Docker 或手动配置安装的版本支持自动更新：

每次重启 Claude Desktop 时自动检查并更新到最新版本
无需手动操作

手动更新（仅限本地源码安装）

1
2
3

cd DesktopCommanderMCP
git pull
npm run setup

卸载

自动卸载（推荐）

1	npx @wonderwhy-er/desktop-commander@latest remove

自动卸载会：

✅ 从 Claude 配置中移除 Desktop Commander
✅ 自动备份配置文件
✅ 提供完整的包移除指导

手动卸载

打开 Claude Desktop 配置文件
删除 "desktop-commander" 条目
保存文件并重启 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

常见问题排查

❌ Claude 无法启动

解决方案:

检查配置文件 JSON 语法是否正确
恢复备份配置文件（自动卸载会创建备份）
临时移除 desktop-commander 配置项

❌ Node.js 未找到

解决方案:

安装 Node.js 18+：访问 nodejs.org
或使用 Docker 安装方式（无需 Node.js）

❌ 命令执行失败

解决方案:

检查 blockedCommands 配置是否阻止了该命令
确认命令在终端中可正常执行
查看日志：~/.claude-server-commander/claude_tool_call.log

❌ Docker 安装后无文件访问权限

解决方案:

确认在 Docker 配置中正确挂载了文件夹（使用 -v 参数）
检查 Docker Desktop 是否正在运行
运行 --status 命令查看 Docker 状态

🔍 获取帮助

Discord 社区: 加入 Discord
GitHub Issues: 提交问题
官方网站: desktopcommander.app

总结

您已了解了 Desktop Commander MCP 的所有安装方式！根据您的需求选择：

快速开始: 使用 npx 安装（方法一）
macOS 用户: 使用 Bash 脚本（方法二）
追求安全: 使用 Docker 安装（方法三）
高级用户: 手动配置（方法四）
开发者: 本地源码安装（方法五）

安装成功后，您就可以让 Claude 执行终端命令、管理文件、分析数据，大幅提升工作效率！

支持项目: 如果觉得有用，请给 GitHub 仓库点个 ⭐，或通过 GitHub Sponsors 支持开发者。