浏览 MCP与Skills教程与资源

Claude Desktop MCP 配置:桌面扩展、JSON、运行环境与日志排错

先分清桌面扩展与手工本地 Server 两条安装路,再用专用样本目录走通手工配置。有效 JSON、能启动的 Node 进程、发现工具和读到文件要分别验证。

安装入口

有桌面扩展时,通常不需要自己维护这份 JSON

Claude Desktop 当前官方入口包括 Settings → Extensions:可以浏览目录并安装扩展,按界面填写目录或账号等配置;自定义扩展使用 .mcpb 包。受组织管理的设备可能由管理员限制可安装范围。扩展自带的运行方式与手工 npx/Node 方式不同,不要把两份定义同时装成重名服务。

以下主线专门讲手工本地 stdio 配置,适合需要理解实际命令、包版本与日志的人。前提是 Windows 或 macOS 的 Claude Desktop,以及你自己安装、能在终端运行的 Node.js/npm。桌面扩展可能使用内置运行环境,不能据此假设手工配置中的 node 或 npx 已在 PATH。

教学使用 Filesystem Server。它有写入和移动能力;本文只发出读取请求,不把整个 Server 称为只读。样本专门放在用户目录下的 mcp-desktop-lab/data,避免用真实桌面、下载或项目目录做第一次练习。

固定练习输入

先读包信息,再安装到独立 runtime 目录

前两段分别适用于 Windows 和 macOS,选择一段准备目录并读取版本。先检查输出中的官方包名、仓库与入口,再运行对应安装命令;命令需要网络并将下载第三方依赖,本站没有替你执行。版本由本次 registry 查询确定,install 用相同版本并保留锁文件,不宣称某个主分支版本就是当前发行版。

Windows PowerShell:准备与查询

固定样本内容与本次版本

node --version
npm --version
$desktopMcpLab = Join-Path $env:USERPROFILE 'mcp-desktop-lab'
New-Item -ItemType Directory -Force -Path (Join-Path $desktopMcpLab 'data') | Out-Null
Set-Content -LiteralPath (Join-Path $desktopMcpLab 'data/probe.txt') -Value 'Desktop MCP sample: 314159' -Encoding UTF8
$desktopFsVersionOutput = npm view @modelcontextprotocol/server-filesystem version
if ($LASTEXITCODE -ne 0 -or -not $desktopFsVersionOutput) { throw '版本查询失败' }
$desktopFsVersion = ([string]$desktopFsVersionOutput).Trim()
npm view "@modelcontextprotocol/server-filesystem@$desktopFsVersion" name version repository.url bin --json
Windows PowerShell:审查后执行

安装固定版本,保留 package-lock.json

npm install --prefix (Join-Path $desktopMcpLab 'runtime') --save-exact --ignore-scripts "@modelcontextprotocol/server-filesystem@$desktopFsVersion"
if ($LASTEXITCODE -ne 0) { throw '安装未完成,不要继续修改 Desktop 配置' }
macOS 终端:准备与查询

与 Windows 使用同一份样本

node --version
npm --version
desktop_mcp_lab="$HOME/mcp-desktop-lab"
mkdir -p "$desktop_mcp_lab/data"
printf '%s\n' 'Desktop MCP sample: 314159' > "$desktop_mcp_lab/data/probe.txt"
desktop_fs_version="$(npm view @modelcontextprotocol/server-filesystem version)"
test -n "$desktop_fs_version" || exit 1
npm view "@modelcontextprotocol/server-filesystem@$desktop_fs_version" name version repository.url bin --json
macOS 终端:审查后执行

安装到专用 runtime

npm install --prefix "$desktop_mcp_lab/runtime" --save-exact --ignore-scripts "@modelcontextprotocol/server-filesystem@$desktop_fs_version"

安装失败时先处理 npm 给出的具体错误。--ignore-scripts 只控制安装生命周期,不阻止稍后显式启动的 Server 代码。已存在同名练习目录时先检查样本文件,本例会重写其中的 probe.txt。

完整配置工件

从当前机器生成绝对路径,减少 GUI PATH 与转义错误

把下面代码保存成 print-desktop-mcp.cjs,再执行 node print-desktop-mcp.cjs。脚本只读取本次安装是否存在,并打印完整 JSON,不会自动覆盖 Desktop 的配置。它直接用当前 Node 可执行文件启动已安装的 JS 入口,避免 Windows 的 npx.cmd 包装以及 GUI 找不到 npx 的另一层问题。

print-desktop-mcp.cjs

生成可粘贴的本机 JSON

const fs = require('node:fs');
const os = require('node:os');
const path = require('node:path');
const lab = path.join(os.homedir(), 'mcp-desktop-lab');
const entry = path.join(lab, 'runtime', 'node_modules', '@modelcontextprotocol', 'server-filesystem', 'dist', 'index.js');
const data = path.join(lab, 'data');
if (!fs.existsSync(entry) || !fs.existsSync(path.join(data, 'probe.txt'))) {
  throw new Error('未找到已安装入口或 probe.txt;先完成准备与安装');
}
console.log(JSON.stringify({
  mcpServers: {
    desktopLabFiles: {
      command: process.execPath,
      args: [entry, data]
    }
  }
}, null, 2));

该配置没有手写 cwd 字段,也没有假设 Desktop 支持其他客户端的字段。生成的 command 与入口是绝对路径;如果以后卸载/更换 Node 或搬动 runtime,必须重新核对这些路径。

Desktop 配置位置

从 Developer 的 Edit Config 进入实际文件

先在运行中的应用 Settings → Developer → Edit Config 确认当前账户的配置文件位置,然后完全退出 Desktop,备份该文件并用日期时间区分每次备份。编辑时,已有 mcpServers 就只合并 desktopLabFiles 这一项,不粘贴整份 JSON 覆盖其他配置。保存后重新启动 Desktop。

系统手工配置日志
Windows%APPDATA%\Claude\claude_desktop_config.json%APPDATA%\Claude\logs\mcp.log;mcp-server-desktopLabFiles.log
macOS~/Library/Application Support/Claude/claude_desktop_config.json~/Library/Logs/Claude/mcp.log;mcp-server-desktopLabFiles.log

具体菜单会随版本变化,记录当前应用版本。Extensions 管理已安装扩展;Developer/Edit Config 管理此处的手工连接,两个入口不要混用。

第一次调用

目录与内容都要对应这一次练习

  1. 01

    先看当前工具和允许目录

    在对话输入框旁的 + → Connectors 或 Developer 状态里找到 desktopLabFiles。要求使用该 Server 的 list_allowed_directories,核对实际范围。Filesystem 支持 Roots 更新目录;如果结果大于预期,先停止样本读取并检查客户端提供的 Roots,不把启动参数当最终边界。

  2. 02

    再读唯一的 probe.txt

    要求只用 desktopLabFiles 读取 data 目录下 probe.txt,返回文件路径和原文。审阅调用对象与参数后再批准。预期正文是 Desktop MCP sample: 314159;不要求写文件,也不让其他工具代做以掩盖失败。

  3. 03

    对照独立的文件内容

    用文本编辑器打开同一个文件,核对路径和原文。得到正确文本证明这次读取成功;它不证明所有文件可读、Server 无写权限或其他客户端同样可用。记录本机版本、安装包版本和本次实际结果。

按阶段排错

先解析、再启动、最后检查调用

保存后提示 JSON 解析失败

原因
常见是尾随逗号、漏括号、中文引号,或 Windows 路径反斜杠未转义。
怎么改
用支持 JSON 诊断的编辑器定位行列。例如最后一项写成 "args": ["a"], 后面直接接 } 就有多余逗号。回到生成脚本的输出,合并时保留标准双引号。先解决解析,再看连接。

mcp.log 提示无法启动命令 / ENOENT

原因
command 所指程序或 args 中脚本路径不存在,或旧 GUI 环境与终端不同。
怎么改
核对 JSON 中的绝对 Node 路径及 dist/index.js。本文已绕开 npx 的 PATH,若仍出现找不到入口,修正实际路径而非无条件增大超时。

Server 启动后退出,工具不出现

原因
入口能执行但运行报错;可能是依赖、目录不存在或版本不兼容。
怎么改
打开 mcp-server-desktopLabFiles.log 读本次 stderr,对照安装版本及样本目录。stderr 也会记录普通诊断,必须看具体错误和退出行为,不把任何日志文字都当失败。

工具可见但 probe.txt Access denied

原因
当前允许目录、Roots 或 OS 文件权限与路径不匹配。
怎么改
先回读 list_allowed_directories 和实际参数,再核对同一账户能否打开文件;不要直接把允许范围改成整个用户目录。

只关了窗口,配置好像没更新

原因
桌面应用可能仍在托盘/菜单栏运行,旧子进程仍在使用。
怎么改
使用应用的退出操作后重开,按日志时间确认新进程。不要在不清楚进程归属时批量结束所有 node 进程。
退出练习

只移除本次连接,保留其他配置

从手工 JSON 的 mcpServers 中删除 desktopLabFiles,保存并完全重开应用。检查工具列表不再出现它,日志不再为该条目新建连接。若是通过 Extensions 安装的同名扩展,还需到该入口分别停用;修改 JSON 不会替你卸载扩展。

runtime 与 data 是本次专用练习目录,先确认没有放入自己的资料再决定是否清理。此时删连接与删磁盘包是两件事。恢复备份前应比对后来新增的其他 Server,避免用旧备份抹掉合法修改。

一手依据

资料与核对范围

资料核对日:2026-10-10。以下来源支持协议与配置说明;文中的命令、练习和预期结果不代表本站已在所有客户端和系统完成实测。