> ## Documentation Index
> Fetch the complete documentation index at: https://mcp.gjxx.dev/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 服务器，这是[支持 MCP 的众多客户端之一](/clients)。虽然我们专注于 Claude Desktop 的实现，但这些概念广泛适用于其他兼容 MCP 的客户端。通过本教程结束时，Claude 将能够与您计算机上的文件进行交互、创建新文档、组织文件夹并搜索您的文件系统——所有这些都需要您对每个操作的明确许可。

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

## Prerequisites

在开始本教程之前，确保您的系统上安装了以下内容：

### Claude Desktop

下载并安装适用于您的操作系统的 [Claude Desktop](https://claude.ai/download)。Claude Desktop 可用于 macOS 和 Windows。

如果您已经安装了 Claude Desktop，请通过单击 Claude 菜单并选择"检查更新..."来验证您运行的是最新版本。

### Node.js

Filesystem Server 和许多其他 MCP 服务器需要 Node.js 来运行。通过打开终端或命令提示符并运行以下命令来验证您的 Node.js 安装：

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

如果未安装 Node.js，请从 [nodejs.org](https://nodejs.org/) 下载。我们推荐 LTS（长期支持）版本以确保稳定性。

## Understanding MCP Servers

MCP 服务器是在您的计算机上运行的程序，通过标准化协议为 Claude Desktop 提供特定能力。每个服务器暴露 Claude 可以使用的工具来执行操作，并需要您的批准。Filesystem Server 我们将安装的提供了以下工具：

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

所有操作都需要您的明确批准才能执行，确保您对 Claude 可以访问和修改的内容保持完全控制。

## Installing the Filesystem Server

该过程涉及配置 Claude Desktop 以在您启动应用程序时自动启动 Filesystem Server。此配置通过一个 JSON 文件完成，该文件告诉 Claude Desktop 要运行哪些服务器以及如何连接到它们。

<Steps>
  <Step title="Open Claude Desktop Settings">
    首先访问 Claude Desktop 设置。单击系统菜单栏中的 Claude 菜单（不是 Claude 窗口内的设置本身）并选择"设置..."

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

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

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

  <Step title="Access Developer Settings">
    在设置窗口中，导航到左侧边栏中的"Developer"选项卡。此部分包含配置 MCP 服务器和其他开发者功能的选项。

    单击"Edit Config"按钮打开配置文件：

    <Frame>
      <img src="https://mintcdn.com/xiaom/moo7OPYtE2GIRmE3/images/quickstart-developer.png?fit=max&auto=format&n=moo7OPYtE2GIRmE3&q=85&s=b5f3bcd35edf295c67780e12ce0ae06e" 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="Configure the 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>
      **Understanding the Configuration**

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

    <Warning>
      **Security Consideration**

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

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

    成功重新启动后，您会在对话输入框的右下角看到 MCP 服务器指示器 <img src="https://mintcdn.com/xiaom/moo7OPYtE2GIRmE3/images/claude-desktop-mcp-slider.svg?fit=max&auto=format&n=moo7OPYtE2GIRmE3&q=85&s=3b112b1a29d2030bcc52ca228aa7a097" 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/xiaom/moo7OPYtE2GIRmE3/images/quickstart-slider.png?fit=max&auto=format&n=moo7OPYtE2GIRmE3&q=85&s=5f6ec35d32b2625e23d6fc78370b6bd7" alt="Claude Desktop interface showing MCP server indicator" width="1414" height="410" data-path="images/quickstart-slider.png" />
    </Frame>

    单击此指示器可查看 Filesystem Server 提供的可用工具：

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

    如果服务器指示器没有出现，请参考[故障排除](#troubleshooting)部分以获取调试步骤。
  </Step>
</Steps>

## Using the Filesystem Server

连接 Filesystem Server 后，Claude 现在可以与您的文件系统进行交互。尝试这些示例请求来探索功能：

### File Management Examples

* **"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 将创建一个文件夹并将图像文件移动到其中

### How Approval Works

在执行任何文件系统操作之前，Claude 将请求您的批准。这确保您对所有操作保持控制：

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

在批准之前仔细审查每个请求。如果您对提议的操作不满意，您可以随时拒绝请求。

## Troubleshooting

如果您在设置或使用 Filesystem Server 时遇到问题，这些解决方案解决了常见问题：

<AccordionGroup>
  <Accordion title="Server not showing up in Claude / hammer icon missing">
    1. 完全重新启动 Claude Desktop
    2. 检查您的 `claude_desktop_config.json` 文件语法
    3. 确保 `claude_desktop_config.json` 中包含的文件路径有效，并且它们是绝对路径而不是相对路径
    4. 查看[日志](#getting-logs-from-claude-for-desktop)以了解服务器未连接的原因
    5. 在您的命令行中，尝试手动运行服务器（替换 `username` 如您在 `claude_desktop_config.json` 中所做）以查看是否收到任何错误：

    <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="Getting logs from 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="Tool calls failing silently">
    如果 Claude 尝试使用工具但失败：

    1. 检查 Claude 的日志是否有错误
    2. 验证您的服务器构建和运行没有错误
    3. 尝试重新启动 Claude Desktop
  </Accordion>

  <Accordion title="None of this is working. What do I do?">
    请参考我们的[调试指南](/legacy/tools/debugging)以获取更好的调试工具和更详细的指导。
  </Accordion>

  <Accordion title="ENOENT error and `${APPDATA}` in paths on Windows">
    如果您的配置服务器无法加载，并且您在日志中看到引用路径中 `${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 should be installed globally**

      如果您没有全局安装 NPM，`npx` 命令可能会继续失败。如果 NPM 已经全局安装，您会在系统上找到 `%APPDATA%\npm`。如果没有，您可以通过运行以下命令全局安装 NPM：

      ```bash theme={null}
      npm install -g npm
      ```
    </Warning>
  </Accordion>
</AccordionGroup>

## Next Steps

现在您已经成功将 Claude Desktop 连接到本地 MCP 服务器，探索这些选项来扩展您的设置：

<CardGroup cols={2}>
  <Card title="Explore other servers" icon="grid" href="https://github.com/modelcontextprotocol/servers">
    浏览我们官方和社区创建的 MCP 服务器集合以获取额外功能
  </Card>

  <Card title="Build your own server" icon="code" href="/docs/develop/build-server">
    创建针对您的特定工作流程和集成的自定义 MCP 服务器
  </Card>

  <Card title="Connect to remote servers" icon="cloud" href="/docs/develop/connect-remote-servers">
    学习如何将 Claude 连接到远程 MCP 服务器以获取基于云的工具和服务
  </Card>

  <Card title="Understand the protocol" icon="book" href="/docs/learn/architecture">
    深入了解 MCP 的工作原理及其架构
  </Card>
</CardGroup>