MCP中文文档
MCP 开发者文档
连接到本地 MCP 服务器

连接到本地 MCP 服务器

社区译文；来源： MCP 80041ab0

Model Context Protocol (MCP) 服务器通过提供安全、受控的本地资源和工具访问，扩展了 AI 应用的能力。许多客户端都支持 MCP，从而在不同平台和应用之间带来多样化的集成可能。

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

Claude Desktop 的文件系统集成，展示文件管理能力

前置条件

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

Claude Desktop

为你的操作系统下载并安装 Claude Desktop 。Claude Desktop 支持 macOS、Windows 和 Linux。

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

Node.js

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

node --version

如果尚未安装 Node.js，请从 nodejs.org 下载。为稳定起见，我们推荐 LTS（Long Term Support）版本。

了解 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 上，它出现在顶部菜单栏中：

Claude Desktop 菜单，展示 Settings 选项

这会打开 Claude Desktop 配置窗口，它与你的 Claude 账号设置是分开的。

访问开发者设置

在 Settings 窗口中，转到左侧边栏的 “Developer” 标签页。这一部分包含配置 MCP 服务器和其他开发者功能的选项。

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

开发者设置，展示 Edit Config 按钮

如果配置文件不存在，此操作会创建一个新文件；否则会打开你现有的配置。该文件位于：

  • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows：%APPDATA%\Claude\claude_desktop_config.json

配置 Filesystem Server

用下面的 JSON 结构替换配置文件的内容。该配置告诉 Claude Desktop 启动 Filesystem Server 并允许其访问特定目录：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/Users/username/Downloads"
      ]
    }
  }
}
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\\Users\\username\\Desktop",
        "C:\\Users\\username\\Downloads"
      ]
    }
  }
}

把 username 替换为你实际的电脑用户名。args 数组中列出的路径指定了 Filesystem Server 可以访问哪些目录。你可以按需修改这些路径或添加其他目录。

理解这份配置

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

安全考虑

只授予 Claude 那些你愿意让它读取和修改的目录的访问权限。服务器以你的用户账号权限运行，因此它能执行你能手动执行的任何文件操作。

重启 Claude Desktop

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

重启成功后，点击对话输入框左下角的 “Add files, connectors, and more /” 指示器 ：

Claude Desktop 界面，展示 MCP 服务器指示器

点击该指示器，然后将鼠标移到 “Connectors” 上并点击 “Manage connectors”。在连接器列表中选择 “filesystem”，即可查看 Filesystem Server 可用的工具：

Claude Desktop 中可用的文件系统工具

如果 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 都会请求你的批准。这确保你始终掌控所有操作：

Claude 请求批准执行文件操作

在批准之前，请仔细查看每一个请求。如果对拟议的操作不放心，你随时可以拒绝。

故障排除

如果你在设置或使用 Filesystem Server 时遇到问题，以下方案可解决常见问题：

服务器没有出现在 Claude 中 / 锤子图标缺失
  1. 完全重启 Claude Desktop
  2. 检查你的 claude_desktop_config.json 文件语法
  3. 确认 claude_desktop_config.json 中包含的文件路径有效，并且是绝对路径而非相对路径
  4. 查看日志 ，了解服务器为何无法连接
  5. 在命令行中尝试手动运行该服务器（像在 claude_desktop_config.json 中那样替换 username），看是否会报错：
npx -y @modelcontextprotocol/server-filesystem /Users/username/Desktop /Users/username/Downloads
npx -y @modelcontextprotocol/server-filesystem C:\Users\username\Desktop C:\Users\username\Downloads
从 Claude Desktop 获取日志

Claude.app 中与 MCP 相关的日志会写入以下日志文件：

  • macOS：~/Library/Logs/Claude

  • Windows：%APPDATA%\Claude\logs

  • mcp.log 包含有关 MCP 连接以及连接失败的一般日志。

  • 名为 mcp-server-SERVERNAME.log 的文件包含对应服务器的 stderr 输出。Stdio 服务器可能把所有日志都写到 stderr，因此这些文件并不只包含错误。

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

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
type "%APPDATA%\Claude\logs\mcp*.log"
工具调用静默失败

如果 Claude 尝试使用工具但调用失败：

  1. 检查 Claude 的日志中是否有错误
  2. 验证你的服务器能正常构建并运行、不报错
  3. 尝试重启 Claude Desktop
以上方法都不奏效，我该怎么办？

请参阅我们的调试指南 ，其中有更好的调试工具和更详细的指引。

Windows 上的 ENOENT 错误与路径中的 `${APPDATA}`

如果你配置的服务器加载失败，并且在其日志中看到某条路径里引用了 ${APPDATA} 的错误，你可能需要把 %APPDATA% 展开后的值添加到 claude_desktop_config.json 的 env 键中：

{
  "brave-search": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-brave-search"],
    "env": {
      "APPDATA": "C:\\Users\\user\\AppData\\Roaming\\",
      "BRAVE_API_KEY": "..."
    }
  }
}

完成这一修改后，再次启动 Claude Desktop。

npm 应全局安装

如果你没有全局安装 npm，npx 命令可能仍会持续失败。如果 npm 已全局安装，你会看到系统中存在 %APPDATA%\npm。如果没有，可以运行以下命令全局安装 npm：

npm install -g npm

后续步骤

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

探索其他服务器

浏览我们收集的官方与社区 MCP 服务器，获取更多能力

构建你自己的服务器

创建针对你特定工作流和集成需求定制的 MCP 服务器

连接到远程服务器

学习如何将 Claude 连接到远程 MCP 服务器，以使用云端工具和服务

理解协议

深入了解 MCP 的工作方式及其架构

理解 MCP 中的授权连接到远程 MCP 服务器