项目简介

文件系统MCP服务器 (MCP Filesystem Server) 是一个基于 Model Context Protocol (MCP) 构建的后端服务，旨在为大型语言模型 (LLM) 客户端提供安全可靠的文件系统访问能力。该服务器允许LLM客户端通过标准化的MCP协议，在预先设定的安全目录范围内，执行文件和目录的读取、写入、编辑、移动、搜索以及元数据获取等操作。它通过严格的路径验证和权限控制，确保LLM只能访问授权目录下的资源，从而有效保护本地文件系统的安全。

主要功能点

安全访问控制：仅允许访问预先配置的目录，防止未授权的文件系统操作。
文件操作：支持读取、写入、编辑和移动文件。
目录操作：支持创建、列出目录内容、获取目录树结构和搜索目录。
元数据访问：提供文件和目录的详细信息，如大小、创建时间、修改时间等。
工具集成：以 MCP Tool 的形式向 LLM 客户端暴露文件系统操作能力，方便 LLM 按需调用。
Docker 部署：提供 Docker 镜像和 Docker Compose 配置，方便快速部署和容器化管理。

安装步骤

克隆仓库

git clone https://github.com/gabrielmaialva33/mcp-filesystem.git
cd mcp-filesystem

安装依赖 确保已安装 Node.js (>=22.13.1), pnpm (>=8.0.0)。然后运行：
```
pnpm install
```
构建项目
```
pnpm build
```

服务器配置

MCP 客户端需要配置以下信息以连接到文件系统MCP服务器。以下是配置示例（JSON 格式）：

{
  "serverName": "filesystem-server",
  "command": "pnpm",
  "args": [
    "start",
    "/path/to/allowed/directory"  // 请替换为允许 LLM 客户端访问的本地目录路径
  ]
}

配置参数说明：

'serverName': 服务器名称，客户端用于标识和管理连接。可以自定义，例如 "filesystem-server"。
'command': 启动服务器的命令。这里使用 'pnpm' 运行 'start' 脚本。
'args': 传递给启动命令的参数，'start' 脚本需要指定至少一个允许访问的目录路径。
- '/path/to/allowed/directory': 请务必替换为实际的本地目录路径。这是服务器允许 LLM 客户端访问的根目录。可以配置多个允许访问的目录，作为额外的参数添加到 'args' 数组中。例如：'["start", "/path/dir1", "/path/dir2"]'。

Docker 部署配置示例：

如果使用 Docker 部署，MCP 客户端的 'command' 和 'args' 配置可以简化，服务器目录映射通过 Docker 卷完成。

{
  "serverName": "filesystem-server-docker",
  "command": "docker",
  "args": [
    "run",
    "-v", "/path/to/data:/data:ro",  // 可选，如果需要挂载只读数据卷
    "mcp-filesystem",
    "/data"                         // Docker 容器内的挂载点，对应服务器允许访问的目录
  ]
}

配置参数说明（Docker 部署）：

'command': 使用 'docker run' 命令启动容器。
'args':
- '-v /path/to/data:/data:ro': 可选，如果需要将宿主机的 '/path/to/data' 目录挂载到容器内的 '/data' 目录，并设置为只读 ('ro')。请根据实际需求配置数据卷挂载。
- 'mcp-filesystem': Docker 镜像名称，根据实际构建的镜像名称填写。
- '/data': 容器启动命令的参数，指定服务器允许访问的目录。这里 '/data' 对应 Dockerfile 中或 'docker run' 命令中挂载的数据卷路径。

基本使用方法

启动服务器 根据选择的部署方式（本地开发、Docker 或 Docker Compose），运行相应的启动命令。例如，本地开发启动服务器并允许访问 '/tmp/my_allowed_dir' 目录：
```
pnpm start /tmp/my_allowed_dir
```
配置 MCP 客户端 在 MCP 客户端 (如 ChatDev 或其他支持 MCP 协议的应用) 中，配置上述的服务器连接信息 (JSON 配置)。
通过客户端调用工具 客户端连接成功后，即可通过自然语言指令或工具调用界面，使用文件系统相关的 Tool，例如：
- 读取文件内容 (read_file)
- 列出目录内容 (list_directory)
- 创建新目录 (create_directory)
- 等等。
客户端会根据 Tool 的定义和参数，向文件系统MCP服务器发送 MCP 请求，服务器执行相应的操作并返回结果给客户端。

注意：

首次运行服务器前，请确保 '/path/to/allowed/directory' (或 Docker 卷挂载的目录) 存在，并且服务器进程有读取和写入权限（根据需要）。
Docker 部署时，请先构建 Docker 镜像 ('docker build -t mcp-filesystem .')。

关键词

项目简介

主要功能点

安装步骤

服务器配置

基本使用方法

信息