> ## Documentation Index
> Fetch the complete documentation index at: https://mcp.developerdoc.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 连接本地 MCP 服务器

> 了解如何通过本地 MCP 服务器扩展 Claude Desktop，实现文件系统访问和其他强大集成

Model Context Protocol（MCP）服务器通过对本地资源和工具提供安全、受控的访问，扩展 AI 应用的能力。许多客户端都支持 MCP，因此可以在不同平台和应用之间实现多样化集成。

本指南以 Claude Desktop 作为示例，演示如何连接本地 MCP 服务器。Claude Desktop 只是众多支持 MCP 的客户端之一；虽然本文聚焦它的实现方式，但这些概念也广泛适用于其他兼容 MCP 的客户端。完成本教程后，Claude 将能够与你电脑上的文件交互、创建新文档、整理文件夹，并搜索文件系统，而且每个动作都需要你的明确许可。

<Frame>
  <img src="https://mintcdn.com/mcp-af858c62/jSqzMzM_desZfWyn/images/quickstart-filesystem.png?fit=max&auto=format&n=jSqzMzM_desZfWyn&q=85&s=8c5e07b10c93b9d93300ae1f40d59f77" alt="Claude Desktop with filesystem integration showing file management capabilities" width="1732" height="2060" data-path="images/quickstart-filesystem.png" />
</Frame>

## 前置条件

开始本教程前，请确保你的系统已安装以下内容：

### Claude Desktop

下载并安装适合你操作系统的 [Claude Desktop](https://claude.ai/download)。Claude Desktop 支持 macOS 和 Windows。

如果你已经安装 Claude Desktop，请点击 Claude 菜单并选择 “Check for Updates...”，确认当前运行的是最新版本。

### Node.js

Filesystem Server 和许多其他 MCP 服务器都需要 Node.js 才能运行。打开终端或命令提示符，运行以下命令检查 Node.js 安装：

```bash theme={null}
node --version
```

如果尚未安装 Node.js，请从 [nodejs.org](https://nodejs.org/) 下载。为了稳定性，建议使用 LTS（Long Term Support）版本。

## 理解 MCP 服务器

MCP 服务器是在你的电脑上运行的程序，并通过标准化协议向 Claude Desktop 提供特定能力。每个服务器都会暴露 Claude 可使用的 tools，并且执行动作前需要你的批准。本文将安装的 Filesystem Server 提供以下 tools：

* 读取文件内容和目录结构
* 创建新文件和目录
* 移动和重命名文件
* 按名称或内容搜索文件

所有动作执行前都需要你的明确批准，确保你完全控制 Claude 可以访问和修改的内容。

## 安装 Filesystem Server

安装过程需要配置 Claude Desktop，使其在启动应用时自动启动 Filesystem Server。这个配置通过一个 JSON 文件完成，用来告诉 Claude Desktop 要运行哪些服务器，以及如何连接它们。

<Steps>
  <Step title="打开 Claude Desktop 设置">
    首先进入 Claude Desktop 设置。点击系统菜单栏中的 Claude 菜单（不是 Claude 窗口内部的设置），然后选择 “Settings...”。

    在 macOS 上，它会出现在顶部菜单栏中：

    <Frame style={{ textAlign: "center" }}>
      <img src="https://mintcdn.com/mcp-af858c62/jSqzMzM_desZfWyn/images/quickstart-menu.png?fit=max&auto=format&n=jSqzMzM_desZfWyn&q=85&s=360031a58d915c33347cb746ab48e802" width="400" alt="Claude Desktop menu showing Settings option" data-path="images/quickstart-menu.png" />
    </Frame>

    这会打开 Claude Desktop 配置窗口，它与 Claude 账户设置是分开的。
  </Step>

  <Step title="进入开发者设置">
    在 Settings 窗口中，进入左侧边栏的 “Developer” 标签页。这里包含配置 MCP 服务器和其他开发者功能的选项。

    点击 “Edit Config” 按钮打开配置文件：

    <Frame>
      <img src="https://mintcdn.com/mcp-af858c62/jSqzMzM_desZfWyn/images/quickstart-developer.png?fit=max&auto=format&n=jSqzMzM_desZfWyn&q=85&s=115ac663466c04f9b5b3f8593a278a7b" 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`
  </Step>

  <Step title="配置 Filesystem Server">
    将配置文件内容替换为以下 JSON 结构。该配置会告诉 Claude Desktop 启动 Filesystem Server，并允许它访问特定目录：

    <CodeGroup>
      ```json macOS theme={null}
      {
        "mcpServers": {
          "filesystem": {
            "command": "npx",
            "args": [
              "-y",
              "@modelcontextprotocol/server-filesystem",
              "/Users/username/Desktop",
              "/Users/username/Downloads"
            ]
          }
        }
      }
      ```

      ```json Windows theme={null}
      {
        "mcpServers": {
          "filesystem": {
            "command": "npx",
            "args": [
              "-y",
              "@modelcontextprotocol/server-filesystem",
              "C:\\Users\\username\\Desktop",
              "C:\\Users\\username\\Downloads"
            ]
          }
        }
      }
      ```
    </CodeGroup>

    将 `username` 替换为你电脑上的实际用户名。`args` 数组中的路径指定 Filesystem Server 可以访问哪些目录。你可以根据需要修改这些路径，或添加更多目录。

    <Tip>
      **理解配置**

      * `"filesystem"`：服务器在 Claude Desktop 中显示的友好名称。
      * `"command": "npx"`：使用 Node.js 的 npx 工具运行服务器。
      * `"-y"`：自动确认安装服务器包。
      * `"@modelcontextprotocol/server-filesystem"`：Filesystem Server 的包名。
      * 其余参数：允许服务器访问的目录。
    </Tip>

    <Warning>
      **安全注意事项**

      只授权 Claude 读取和修改你愿意开放的目录。服务器会以你的用户账户权限运行，因此它可以执行你手动能执行的任何文件操作。
    </Warning>
  </Step>

  <Step title="重启 Claude Desktop">
    保存配置文件后，完全退出 Claude Desktop 并重新启动。应用需要重启才能加载新配置并启动 MCP 服务器。

    重启成功后，你会在对话输入框右下角看到 MCP server 指示器 <img src="https://mintcdn.com/mcp-af858c62/jSqzMzM_desZfWyn/images/claude-desktop-mcp-slider.svg?fit=max&auto=format&n=jSqzMzM_desZfWyn&q=85&s=57cfcf15e5088c7444a948fdc0aa2a0c" style={{display: 'inline', margin: 0, height: '1.3em'}} width="24" height="24" data-path="images/claude-desktop-mcp-slider.svg" />：

    <Frame>
      <img src="https://mintcdn.com/mcp-af858c62/jSqzMzM_desZfWyn/images/quickstart-slider.png?fit=max&auto=format&n=jSqzMzM_desZfWyn&q=85&s=f38e7661a4dc6ed6adbd05bd7db5334a" alt="Claude Desktop interface showing MCP server indicator" width="1414" height="410" data-path="images/quickstart-slider.png" />
    </Frame>

    点击该指示器可以查看 Filesystem Server 提供的可用 tools：

    <Frame style={{ textAlign: "center" }}>
      <img src="https://mintcdn.com/mcp-af858c62/jSqzMzM_desZfWyn/images/quickstart-tools.png?fit=max&auto=format&n=jSqzMzM_desZfWyn&q=85&s=b58b7b2f3b3dacaeec7fbcefe5677d62" width="400" alt="Available filesystem tools in Claude Desktop" data-path="images/quickstart-tools.png" />
    </Frame>

    如果服务器指示器没有出现，请参考[排障](#troubleshooting)部分进行调试。
  </Step>
</Steps>

## 使用 Filesystem Server

连接 Filesystem Server 后，Claude 就可以与你的文件系统交互。可以尝试以下示例请求来探索能力：

### 文件管理示例

* **“你能写一首诗并保存到我的桌面吗？”** - Claude 会创作一首诗，并在你的桌面创建新的文本文件。
* **“我的下载文件夹里有哪些工作相关文件？”** - Claude 会扫描下载目录并识别工作相关文档。
* **“请把我桌面上的所有图片整理到一个叫 Images 的新文件夹里。”** - Claude 会创建文件夹并将图片文件移入其中。

### 审批如何工作

在执行任何文件系统操作之前，Claude 都会请求你的批准。这确保你能控制所有动作：

<Frame style={{ textAlign: "center" }}>
  <img src="https://mintcdn.com/mcp-af858c62/jSqzMzM_desZfWyn/images/quickstart-approve.png?fit=max&auto=format&n=jSqzMzM_desZfWyn&q=85&s=045fe0076f6cae8f410d8bf0f43f6c5c" width="500" alt="Claude requesting approval to perform a file operation" data-path="images/quickstart-approve.png" />
</Frame>

批准前请仔细检查每个请求。如果你不认可拟执行的动作，可以随时拒绝。

## 排障

如果在设置或使用 Filesystem Server 时遇到问题，以下方案可以处理常见情况：

<AccordionGroup>
  <Accordion title="服务器没有出现在 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`），看看是否报错：

    <CodeGroup>
      ```bash macOS/Linux theme={null}
      npx -y @modelcontextprotocol/server-filesystem /Users/username/Desktop /Users/username/Downloads
      ```

      ```powershell Windows theme={null}
      npx -y @modelcontextprotocol/server-filesystem C:\Users\username\Desktop C:\Users\username\Downloads
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="获取 Claude Desktop 日志">
    Claude.app 中与 MCP 相关的日志会写入以下日志文件目录：

    * macOS: `~/Library/Logs/Claude`

    * Windows: `%APPDATA%\Claude\logs`

    * `mcp.log` 包含 MCP 连接和连接失败的一般日志。

    * 名为 `mcp-server-SERVERNAME.log` 的文件包含对应服务器的错误（stderr）日志。

    你可以运行以下命令列出最近日志，并持续跟踪新增日志（在 Windows 上只会显示最近日志）：

    <CodeGroup>
      ```bash macOS/Linux theme={null}
      tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
      ```

      ```powershell Windows theme={null}
      type "%APPDATA%\Claude\logs\mcp*.log"
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="工具调用静默失败">
    如果 Claude 尝试使用 tools 但调用失败：

    1. 检查 Claude 日志中的错误。
    2. 确认服务器可以无错误构建和运行。
    3. 尝试重启 Claude Desktop。
  </Accordion>

  <Accordion title="这些都不生效，我该怎么办？">
    请参考[调试指南](/docs/tools/debugging)，其中提供更好的调试工具和更详细的指导。
  </Accordion>

  <Accordion title="Windows 路径中出现 ENOENT 错误和 `${APPDATA}`">
    如果已配置的服务器加载失败，并且在日志中看到路径里引用 `${APPDATA}` 的错误，你可能需要在 `claude_desktop_config.json` 的 `env` 键中加入展开后的 `%APPDATA%` 值：

    ```json theme={null}
    {
      "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 theme={null}
      npm install -g npm
      ```
    </Warning>
  </Accordion>
</AccordionGroup>

## 后续步骤

现在你已经成功将 Claude Desktop 连接到本地 MCP 服务器，可以探索以下选项来扩展设置：

<CardGroup cols={2}>
  <Card title="探索其他服务器" icon="grid" href="https://github.com/modelcontextprotocol/servers">
    浏览官方和社区创建的 MCP 服务器集合，获取更多能力
  </Card>

  <Card title="构建自己的服务器" icon="code" href="/docs/develop/build-server">
    创建适配你特定工作流和集成需求的自定义 MCP 服务器
  </Card>

  <Card title="连接远程服务器" icon="cloud" href="/docs/develop/connect-remote-servers">
    了解如何将 Claude 连接到远程 MCP 服务器，以使用基于云的工具和服务
  </Card>

  <Card title="理解协议" icon="book" href="/docs/learn/architecture">
    深入了解 MCP 的工作方式和架构
  </Card>
</CardGroup>