Filesystem MCP Server 是一个基于 Node.js 的 Model Context Protocol (MCP) 服务器，提供文件系统操作能力。它通过 npm 包 @modelcontextprotocol/server-filesystem 发布。

功能特性

读写文件

创建/列出/删除目录

移动文件/目录

搜索文件

获取文件元数据

通过 Roots 实现动态目录访问控制

前置条件

Node.js 16+（使用 npx 方式）

Docker（使用 Docker 方式）

支持 MCP 的客户端（如 Claude Desktop、VS Code）

安装与配置

方式一：npx（推荐）

Claude Desktop 配置（macOS/Linux）：

json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/path/to/other/allowed/dir"
      ]
    }
  }
}

Windows 用户：

json
{
  "mcpServers": {
    "filesystem": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/path/to/other/allowed/dir"
      ]
    }
  }
}

方式二：Docker

所有目录必须挂载到 /projects 下。添加 ro 标志可使目录只读。

json
{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount", "type=bind,src=/Users/username/Desktop,dst=/projects/Desktop",
        "--mount", "type=bind,src=/path/to/other/allowed/dir,dst=/projects/other/allowed/dir,ro",
        "--mount", "type=bind,src=/path/to/file.txt,dst=/projects/path/to/file.txt",
        "mcp/filesystem",
        "/projects"
      ]
    }
  }
}

方式三：VS Code 集成

快速安装按钮：

 

手动配置（用户级，推荐）： 打开命令面板（Ctrl + Shift + P），运行 MCP: Open User Configuration，在 mcp.json 中添加：

json
{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${workspaceFolder}"
      ]
    }
  }
}

Windows 用户：

json
{
  "servers": {
    "filesystem": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${workspaceFolder}"
      ]
    }
  }
}

Docker 方式：

json
{
  "servers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount", "type=bind,src=${workspaceFolder},dst=/projects/workspace",
        "mcp/filesystem",
        "/projects"
      ]
    }
  }
}

目录访问控制

服务器使用灵活的目录访问控制系统，支持两种方式：

方法一：命令行参数

启动时指定允许访问的目录：

bash
mcp-server-filesystem /path/to/dir1 /path/to/dir2

方法二：MCP Roots（推荐）

支持 Roots 的 MCP 客户端可以动态更新允许的目录。客户端通知的 Roots 会完全替换服务器端的允许目录。

重要：如果服务器启动时没有命令行参数，且客户端不支持 Roots 协议（或提供空的 Roots），服务器将在初始化时抛出错误。

工作流程

服务器启动：使用命令行参数中的目录（如有）；无参数则启动时允许目录为空

客户端连接与初始化：客户端发送 initialize 请求，服务器检查客户端是否支持 Roots 协议（capabilities.roots）

Roots 协议处理（客户端支持时）：

- 初始化时：服务器通过 roots/list 请求客户端的 Roots，并替换所有允许目录 - 运行时更新：客户端发送 notifications/roots/list_changed，服务器重新获取 Roots 并替换

回退行为（客户端不支持时）：仅使用命令行参数中的目录，无法动态更新

访问控制：所有文件系统操作限制在允许目录内，使用 list_allowed_directories 工具查看当前目录

可用工具

工具描述输入参数

read_text_file读取文本文件内容path (string), head (number, 可选), tail (number, 可选) read_media_file读取媒体文件返回 base64path (string) read_multiple_files同时读取多个文件paths (string[]) write_file创建或覆盖文件path (string), content (string) edit_file选择性编辑文件path (string), edits (array), dryRun (boolean) create_directory创建目录path (string) list_directory列出目录内容path (string) list_directory_with_sizes列出目录内容及大小path (string), sortBy (string, 可选) move_file移动/重命名文件或目录source (string), destination (string) search_files递归搜索文件path (string), pattern (string), excludePatterns (string[]) directory_tree获取目录树 JSONpath (string), excludePatterns (string[]) get_file_info获取文件/目录元数据path (string) list_allowed_directories列出允许访问的目录无

工具注解（MCP Hints）

服务器为每个工具设置了 MCP ToolAnnotations：

工具readOnlyHintidempotentHintdestructiveHint

read_text_filetrue–– read_media_filetrue–– read_multiple_filestrue–– list_directorytrue–– list_directory_with_sizestrue–– directory_treetrue–– search_filestrue–– get_file_infotrue–– list_allowed_directoriestrue–– create_directoryfalsetruefalse write_filefalsetruetrue edit_filefalsefalsetrue move_filefalsefalsetrue

所有工具均设置 openWorldHint: false，表示仅访问本地文件系统。

动态 Roots 与注意事项

使用 edit_file 时，建议先用 dryRun: true 预览变更

read_text_file 始终按 UTF-8 处理文件，不能同时指定 head 和 tail

move_file 在目标已存在时会失败

服务器至少需要一个允许目录才能运行

FAQ

Q1: 启动时提示 "No allowed directories" 错误？ A: 服务器需要至少一个允许目录。请确保在命令行参数中指定了目录，或者客户端支持 Roots 协议并提供了有效的 Roots。

Q2: 如何动态添加新的允许目录？ A: 使用支持 Roots 的客户端（如 Claude Desktop），通过 Roots 协议更新。客户端发送 notifications/roots/list_changed 通知后，服务器会自动获取新的 Roots 列表。

Q3: Docker 方式下文件权限问题？ A: 确保 Docker 挂载的目录有正确的读写权限。可以使用 ro 标志将目录设为只读，如 --mount type=bind,src=/path,dst=/projects/path,ro。

Q4: Windows 上 npx 启动失败？ A: 需要使用 cmd /c 方式启动，如配置示例所示。确保路径使用正斜杠或双反斜杠。

Q5: 如何查看当前允许的目录？ A: 使用 list_allowed_directories 工具，无需输入参数即可返回当前允许的目录列表。

*最后更新：2026 年 7 月。以官方 @modelcontextprotocol/server-filesystem 为准。*