主题
连接到本地 MCP 服务端
了解如何使用本地 MCP 服务端扩展 Claude Desktop，以实现文件系统访问和其他强大的集成
Model Context Protocol (MCP) 服务端通过提供对本地资源和工具的安全、受控访问，扩展了 AI 应用的能力。许多客户端都支持 MCP，从而在不同平台和应用之间实现多样化的集成可能。
本指南以 Claude Desktop 为例，演示如何连接到本地 MCP 服务端，它是众多支持 MCP 的客户端之一。虽然我们聚焦于 Claude Desktop 的实现，但这些概念广泛适用于其他兼容 MCP 的客户端。完成本教程后，Claude 将能够与您计算机上的文件交互、创建新文档、整理文件夹，并搜索您的文件系统——每一项操作都需要您的明确许可。
前提条件
在开始本教程之前，请确保您的系统上已安装以下内容：
Claude Desktop
下载并安装适用于您操作系统的 Claude Desktop。Claude Desktop 可用于 macOS 和 Windows。
如果您已经安装了 Claude Desktop，请点击 Claude 菜单并选择 "Check for Updates..."，以确认您运行的是最新版本。
Node.js
Filesystem Server 和许多其他 MCP 服务端需要 Node.js 才能运行。打开终端或命令提示符并运行以下命令，以验证您的 Node.js 安装：
bash
node --version如果尚未安装 Node.js，请从 nodejs.org 下载。我们推荐使用 LTS（长期支持）版本以确保稳定性。
了解 MCP 服务端
MCP 服务端是运行在您计算机上的程序，通过标准化协议为 Claude Desktop 提供特定能力。每个服务端都暴露 Claude 可用于执行操作的工具，且需经您批准。我们将安装的 Filesystem Server 提供以下工具：
- 读取文件内容和目录结构
- 创建新文件和目录
- 移动和重命名文件
- 按名称或内容搜索文件
所有操作在执行前都需要您的明确批准，确保您始终完全掌控 Claude 可以访问和修改的内容。
安装 Filesystem Server
该过程包括配置 Claude Desktop，使其在您每次启动应用时自动启动 Filesystem Server。此配置通过一个 JSON 文件完成，该文件告诉 Claude Desktop 要运行哪些服务端以及如何连接到它们。
打开 Claude Desktop 设置
首先访问 Claude Desktop 设置。点击系统菜单栏中的 Claude 菜单（不是 Claude 窗口内部的设置），然后选择 "Settings..."
在 macOS 上，它出现在顶部菜单栏中：
<Frame style="text-align:center">
<img loading="lazy" src="/mcp-img/76e33f3c1ab6.png" width="400" alt="Claude Desktop menu showing Settings option" data-path="images/quickstart-menu.png" />
</Frame>
这将打开 Claude Desktop 配置窗口，它独立于您的 Claude 账户设置。
访问开发者设置
在 Settings 窗口中，导航到左侧边栏中的 "Developer" 选项卡。此部分包含用于配置 MCP 服务端和其他开发者功能的选项。
点击 "Edit Config" 按钮以打开配置文件：
<Frame>
<img loading="lazy" src="/mcp-img/3bb422487646.png" alt="Developer settings showing Edit Config button" width="1688" height="534" data-path="images/quickstart-developer.png" />
</Frame>
此操作会在配置文件不存在时创建一个新文件，或打开您现有的配置。该文件位于：
* **macOS**：`~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows**：`%APPDATA%\Claude\claude_desktop_config.json`
配置 Filesystem Server
将配置文件的内容替换为以下 JSON 结构。此配置告诉 Claude Desktop 启动 Filesystem Server 并授予对特定目录的访问权限：
json
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/username/Desktop",
"/Users/username/Downloads"
]
}
}
}json
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"C:\\Users\\username\\Desktop",
"C:\\Users\\username\\Downloads"
]
}
}
}将 `username` 替换为您实际的计算机用户名。`args` 数组中列出的路径指定了 Filesystem Server 可以访问的目录。您可以根据需要修改这些路径或添加其他目录。
TIP
理解配置
"filesystem"：服务端的友好名称，会显示在 Claude Desktop 中"command": "npx"：使用 Node.js 的 npx 工具来运行服务端"-y"：自动确认服务端软件包的安装"@modelcontextprotocol/server-filesystem"：Filesystem Server 的软件包名称- 其余参数：允许服务端访问的目录
WARNING
安全注意事项
只授予您愿意让 Claude 读取和修改的目录的访问权限。服务端以您的用户账户权限运行，因此它可以执行您手动能执行的任何文件操作。
重启 Claude Desktop
保存配置文件后，完全退出 Claude Desktop 并重新启动它。应用需要重启以加载新配置并启动 MCP 服务端。
成功重启后，点击对话输入框左下角的 "Add files, connectors, and more /" 指示器 <img loading="lazy" src="/mcp-img/21ddb6a561ea.png" style="display:inline;margin:0;height:1.3em;width:auto" width="33" height="33" data-path="images/claude-add-files-connectors-and-more.png" />：
<Frame>
<img loading="lazy" src="/mcp-img/4b2d2e6c4bad.png" alt="Claude Desktop interface showing MCP server indicator" width="1414" height="410" data-path="images/quickstart-slider.png" />
</Frame>
点击此指示器，然后将鼠标移到 "Connectors" 上并点击 "Manage connectors"。从连接器列表中选择 "filesystem"，以查看 Filesystem Server 可用的工具：
<Frame style="text-align:center">
<img loading="lazy" src="/mcp-img/e5101ddeb327.png" width="400" alt="Available filesystem tools in Claude Desktop" data-path="images/quickstart-tools.png" />
</Frame>
如果 Filesystem Server 未能连接，请参阅[故障排除](#故障排除)部分了解调试步骤。
使用 Filesystem Server
Filesystem Server 连接后，Claude 现在可以与您的文件系统交互。尝试以下示例请求以探索其能力：
文件管理示例
- "Can you write a poem and save it to my desktop?" - Claude 将创作一首诗并在您的桌面上创建一个新的文本文件
- "What work-related files are in my downloads folder?" - Claude 将扫描您的下载文件夹并识别与工作相关的文档
- "Please organize all images on my desktop into a new folder called 'Images'" - Claude 将创建一个文件夹并将图像文件移入其中
批准机制如何运作
在执行任何文件系统操作之前，Claude 都会请求您的批准。这确保您对所有操作保持控制：
在批准之前请仔细审查每个请求。如果您对提议的操作感到不安，随时可以拒绝请求。
故障排除
如果您在设置或使用 Filesystem Server 时遇到问题，以下解决方案可解决常见问题：
服务端未显示在 Claude 中 / 锤子图标缺失
1. 完全重启 Claude Desktop
2. 检查您的 `claude_desktop_config.json` 文件语法
3. 确保 `claude_desktop_config.json` 中包含的文件路径有效，且为绝对路径而非相对路径
4. 查看[日志](#getting-logs-from-claude-for-desktop)以了解服务端为何无法连接
5. 在命令行中，尝试手动运行服务端（像在 `claude_desktop_config.json` 中那样替换 `username`），看看是否会得到任何错误：
bash
npx -y @modelcontextprotocol/server-filesystem /Users/username/Desktop /Users/username/Downloadspowershell
npx -y @modelcontextprotocol/server-filesystem C:\Users\username\Desktop C:\Users\username\Downloads从 Claude Desktop 获取日志
与 MCP 相关的 Claude.app 日志会写入以下位置的日志文件：
* macOS：`~/Library/Logs/Claude`
* Windows：`%APPDATA%\Claude\logs`
* `mcp.log` 将包含有关 MCP 连接和连接失败的常规日志。
* 名为 `mcp-server-SERVERNAME.log` 的文件将包含指定服务端的 stderr 输出。Stdio 服务端可能会将所有日志记录到 stderr，因此这些文件不仅限于错误。
您可以运行以下命令来列出最近的日志并跟踪任何新日志（在 Windows 上，它只会显示最近的日志）：
bash
tail -n 20 -f ~/Library/Logs/Claude/mcp*.logpowershell
type "%APPDATA%\Claude\logs\mcp*.log"工具调用静默失败
如果 Claude 尝试使用工具但它们失败了：
- 检查 Claude 的日志以查找错误
- 验证您的服务端能够构建并运行且无错误
- 尝试重启 Claude Desktop
这些都不起作用。我该怎么办？
请参阅我们的调试指南，以获取更好的调试工具和更详细的指导。
Windows 上的 ENOENT 错误和路径中的 ${APPDATA}
如果您配置的服务端加载失败，并且在其日志中看到引用路径中 `${APPDATA}` 的错误，您可能需要将 `%APPDATA%` 的展开值添加到 `claude_desktop_config.json` 中的 `env` 键：
```json
{
"brave-search": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-brave-search"],
"env": {
"APPDATA": "C:\\Users\\user\\AppData\\Roaming\\",
"BRAVE_API_KEY": "..."
}
}
}
```
完成此更改后，再次启动 Claude Desktop。
WARNING
npm 应全局安装
如果您尚未全局安装 npm，npx 命令可能会继续失败。如果 npm 已全局安装，您会在系统上找到 %APPDATA%\npm。如果没有，您可以通过运行以下命令全局安装 npm：
bash
npm install -g npm后续步骤
现在您已成功将 Claude Desktop 连接到本地 MCP 服务端，请探索以下选项以扩展您的设置：