烂翻译系列之——MCP开发——连接本地MCP服务

Learn how to extend Claude Desktop with local MCP servers to enable file system access and other powerful integrations

了解如何通过本地 MCP 服务扩展 Claude Desktop 的功能，以实现文件系统访问及其他强大的集成功能。

Model Context Protocol (MCP) servers extend AI applications’ capabilities by providing secure, controlled access to local resources and tools. Many clients support MCP, enabling diverse integration possibilities across different platforms and applications.

MCP服务通过提供对本地资源和工具的安全、可控访问，扩展了 AI 应用的能力。许多客户端都支持 MCP，使得跨不同平台和应用的多样化集成成为可能。

This guide demonstrates how to connect to local MCP servers using Claude Desktop as an example, one of the many clients that support MCP. While we focus on Claude Desktop’s implementation, the concepts apply broadly to other MCP-compatible clients. By the end of this tutorial, Claude will be able to interact with files on your computer, create new documents, organize folders, and search through your file system—all with your explicit permission for each action.

本指南以 Claude Desktop 为例，演示如何连接到本地 MCP 服务——这是众多支持 MCP 的客户端之一。尽管我们以 Claude Desktop 的实现为重点，但其中的概念广泛适用于其他兼容 MCP 的客户端。

Prerequisites 前置条件

Before starting this tutorial, ensure you have the following installed on your system:

Claude Desktop

Download and install Claude Desktop for your operating system. Claude Desktop is currently available for macOS and Windows. Linux support is coming soon.

下载并为您使用的操作系统安装 Claude Desktop。目前，Claude Desktop 支持 macOS 和 Windows 系统，Linux 版本即将推出。

If you already have Claude Desktop installed, verify you’re running the latest version by clicking the Claude menu and selecting “Check for Updates…”

如果您已安装 Claude Desktop，请通过点击 Claude 菜单并选择“检查更新…”来确认您运行的是最新版本。

Node.js

The Filesystem Server and many other MCP servers require Node.js to run. Verify your Node.js installation by opening a terminal or command prompt and running:

文件系统服务（Filesystem Server）以及许多其他 MCP 服务需要 Node.js 才能运行。请通过打开终端或命令提示符并运行以下命令，验证您的 Node.js 是否已正确安装：

node --version

If Node.js is not installed, download it from nodejs.org. We recommend the LTS (Long Term Support) version for stability.

如果尚未安装 Node.js，请从 nodejs.org 下载。我们推荐使用 LTS（长期支持）版本，以确保稳定性。

Understanding MCP Servers 了解 MCP 服务

MCP servers are programs that run on your computer and provide specific capabilities to Claude Desktop through a standardized protocol. Each server exposes tools that Claude can use to perform actions, with your approval. The Filesystem Server we’ll install provides tools for:

MCP 服务是运行在您本地计算机上的程序，通过标准化的协议向 Claude Desktop 提供特定功能。每个服务都会暴露一系列工具，供 Claude 在获得您授权的前提下使用。我们将要安装的文件系统服务（Filesystem Server）提供了以下功能：

Reading file contents and directory structures 读取文件内容和目录结构
Creating new files and directories 创建新的文件和文件夹
Moving and renaming files 移动和重命名文件
Searching for files by name or content 按名称或内容搜索文件

All actions require your explicit approval before execution, ensuring you maintain full control over what Claude can access and modify.

所有操作在执行前都必须经过您的明确批准，确保您始终对 Claude 可访问和可修改的内容拥有完全控制权。

Installing the Filesystem Server 安装文件系统服务

The process involves configuring Claude Desktop to automatically start the Filesystem Server whenever you launch the application. This configuration is done through a JSON file that tells Claude Desktop which servers to run and how to connect to them.

该过程包括配置 Claude Desktop，使其在每次启动应用时自动运行文件系统服务。此配置通过一个 JSON 文件完成，该文件告知 Claude Desktop 应运行哪些服务以及如何连接到它们。

Open Claude Desktop Settings 打开 Claude Desktop 设置

Start by accessing the Claude Desktop settings. Click on the Claude menu in your system’s menu bar (not the settings within the Claude window itself) and select “Settings…”

首先，进入 Claude Desktop 的设置界面。点击系统菜单栏中的 Claude 菜单（注意：不是 Claude 窗口内的设置），然后选择“设置…”。

On macOS, this appears in the top menu bar:

在 macOS 上，该菜单位于屏幕顶部菜单栏：

This opens the Claude Desktop configuration window, which is separate from your Claude account settings.

这将打开 Claude Desktop 的配置窗口，该窗口独立于您的 Claude 账户设置。
Access Developer Settings 访问开发者设置

In the Settings window, navigate to the “Developer” tab in the left sidebar. This section contains options for configuring MCP servers and other developer features.

在设置窗口中，点击左侧边栏的“开发者”选项卡。该部分包含用于配置 MCP 服务及其他开发功能的选项。

Click the “Edit Config” button to open the configuration file:

点击“编辑配置”按钮，以打开配置文件：

This action creates a new configuration file if one doesn’t exist, or opens your existing configuration. The file is located at:

此操作会在配置文件不存在时创建一个新文件，或打开您已有的配置文件。该文件位于：
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

Configure the Filesystem Server 配置文件系统服务

Replace the contents of the configuration file with the following JSON structure. This configuration tells Claude Desktop to start the Filesystem Server with access to specific directories:

将配置文件的内容替换为以下 JSON 结构。该配置告知 Claude Desktop 启动文件系统服务，并授予其对特定目录的访问权限：

macOS Windows

{
  "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"
      ]
    }
  }
}

Replace username with your actual computer username. The paths listed in the args array specify which directories the Filesystem Server can access. You can modify these paths or add additional directories as needed.

将 username 替换为你计算机的实际用户名。args 数组中列出的路径指定了文件系统服务可以访问的目录。你可以根据需要修改这些路径或添加其他目录。

Understanding the Configuration 理解配置

"filesystem": A friendly name for the server that appears in Claude Desktop 在 Claude Desktop 中显示的服务友好名称
"command": "npx": Uses Node.js’s npx tool to run the server 使用 Node.js 的 npx 工具来运行服务
"-y": Automatically confirms the installation of the server package 自动确认安装服务包
"@modelcontextprotocol/server-filesystem": The package name of the Filesystem Server 文件系统服务的包名称
The remaining arguments: Directories the server is allowed to access 其余参数：服务允许访问的目录

Security Consideration 安全注意事项

Only grant access to directories you’re comfortable with Claude reading and modifying. The server runs with your user account permissions, so it can perform any file operations you can perform manually.

仅授予你允许 Claude 读取和修改的目录的权限。该服务将以你的用户账户权限运行，因此它可以执行你手动能够完成的任何文件操作。

Restart Claude Desktop

After saving the configuration file, completely quit Claude Desktop and restart it. The application needs to restart to load the new configuration and start the MCP server.

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

Upon successful restart, you’ll see an MCP server indicator in the bottom-right corner of the conversation input box:

成功重启后，你会在对话输入框的右下角看到一个 MCP 服务指示图标：

Click on this indicator to view the available tools provided by the Filesystem Server:

点击此指示图标，即可查看文件系统服务提供的可用工具：

If the server indicator doesn’t appear, refer to the Troubleshooting section for debugging steps.

如果服务指示图标未出现，请参考“故障排除”部分中的调试步骤。

Using the Filesystem Server 使用文件系统服务

With the Filesystem Server connected, Claude can now interact with your file system. Try these example requests to explore the capabilities:

连接文件系统服务后，Claude 现在可以与你的文件系统进行交互。尝试以下示例请求，以了解其功能：

File Management Examples 文件管理示例

“Can you write a poem and save it to my desktop?” - Claude will compose a poem and create a new text file on your desktop “你能写一首诗并保存到我的桌面吗？” — Claude 将创作一首诗，并在你的桌面上创建一个新的文本文件
“What work-related files are in my downloads folder?” - Claude will scan your downloads and identify work-related documents “我的下载文件夹中有哪些与工作相关的文件？” — Claude 将扫描你的下载文件夹并识别出与工作相关的文档
“Please organize all images on my desktop into a new folder called ‘Images’” - Claude will create a folder and move image files into it “请将我桌面上所有图片整理到一个名为‘图片’的新文件夹中” — Claude 将创建一个文件夹，并将图片文件移动进去

How Approval Works 审批机制说明

Before executing any file system operation, Claude will request your approval. This ensures you maintain control over all actions:

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

Review each request carefully before approving. You can always deny a request if you’re not comfortable with the proposed action.

在批准之前，请仔细审查每个请求。如果你对提议的操作感到不安，可以随时拒绝该请求。

Troubleshooting 故障排除

If you encounter issues setting up or using the Filesystem Server, these solutions address common problems:

如果在设置或使用文件系统服务时遇到问题，以下解决方案可解决常见问题：

Server not showing up in Claude / hammer icon missing 服务未在 Claude 中显示 / 锤子图标缺失

Restart Claude Desktop completely 完全重启 Claude Desktop
Check your claude_desktop_config.json file syntax 检查你的 claude_desktop_config.json 文件语法是否正确
Make sure the file paths included in claude_desktop_config.json are valid and that they are absolute and not relative 确保 claude_desktop_config.json 中包含的文件路径有效，并且使用的是绝对路径而非相对路径
Look at logs to see why the server is not connecting 查看日志，确认服务无法连接的原因
In your command line, try manually running the server (replacing username as you did in claude_desktop_config.json) to see if you get any errors: 在命令行中尝试手动运行服务（将命令中的 username 替换为你在 claude_desktop_config.json 中设置的实际用户名），以检查是否出现任何错误：

macOS/Linux	Windows
`npx -y @modelcontextprotocol/server-filesystem /Users/username/Desktop /Users/username/Downloads`	`npx -y @modelcontextprotocol/server-filesystem C:\Users\username\Desktop C:\Users\username\Downloads`

Getting logs from Claude Desktop 从 Claude Desktop 获取日志

Claude.app logging related to MCP is written to log files in:

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

macOS: ~/Library/Logs/Claude
Windows: %APPDATA%\Claude\logs
mcp.log will contain general logging about MCP connections and connection failures. mcp.log 文件将包含有关 MCP 连接及连接失败的一般日志信息。
Files named mcp-server-SERVERNAME.log will contain error (stderr) logging from the named server. 名为 mcp-server-SERVERNAME.log 的文件将包含指定服务输出的错误日志（stderr）。

You can run the following command to list recent logs and follow along with any new ones (on Windows, it will only show recent logs):

你可以运行以下命令来列出最近的日志，并实时跟踪新生成的日志（在 Windows 上，该命令仅显示最近的日志）：

macOS/Linux	Windows
`tail -n 20 -f ~/Library/Logs/Claude/mcp*.log`	`type "%APPDATA%\Claude\logs\mcp*.log"`

Tool calls failing silently 工具调用静默失败

If Claude attempts to use the tools but they fail:

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

Check Claude’s logs for errors 检查 Claude 的日志文件中是否有错误信息
Verify your server builds and runs without errors 确认你的服务能够成功构建并正常运行，无任何错误
Try restarting Claude Desktop 尝试完全重启 Claude Desktop

None of this is working. What do I do? 以上方法均无效。我该怎么办？

Please refer to our debugging guide for better debugging tools and more detailed guidance.

请参考我们的调试指南，获取更强大的调试工具和更详细的指导。

ENOENT error and `${APPDATA}` in paths on Windows Windows 上的 ENOENT 错误与路径中的${APPDATA} 解析问题

If your configured server fails to load, and you see within its logs an error referring to ${APPDATA} within a path, you may need to add the expanded value of %APPDATA% to your env key in claude_desktop_config.json:

如果配置的服务无法加载，并且在日志中看到错误信息提及路径中的 ${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": "..."
    }
  }
}

With this change in place, launch Claude Desktop once again.

完成此项更改后，重新启动 Claude Desktop。

NPM should be installed globally NPM 应该全局安装

The npx command may continue to fail if you have not installed NPM globally. If NPM is already installed globally, you will find %APPDATA%\npm exists on your system. If not, you can install NPM globally by running the following command:

如果未全局安装 NPM，npx 命令可能会持续失败。如果已全局安装 NPM，你可以在系统中找到 %APPDATA%\npm 目录。如果该目录不存在，可通过运行以下命令来全局安装 NPM：
npm install -g npm

Next Steps 下一步

Now that you’ve successfully connected Claude Desktop to a local MCP server, explore these options to expand your setup:

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

菜鸟吊思