使用说明

项目简介

Filesystem MCP Server (@sylphlab/filesystem-mcp) 是一个基于 Model Context Protocol (MCP) 构建的后端服务器，旨在为 AI Agent (如 Cline/Claude) 提供安全、高效且节省 Token 的项目文件系统访问能力。它允许 AI Agent 通过标准化的 MCP 协议，安全地读取、写入、编辑和管理项目文件，所有操作均限定在项目根目录下，确保安全性。

主要功能点

安全可靠的项目根目录访问： 所有文件操作都被限制在服务器启动时的工作目录（cwd）内，防止 AI Agent 访问项目根目录之外的文件，保障数据安全。
高效批量操作： 支持批量文件操作，例如一次读取多个文件内容，减少 AI Agent 与服务器之间的往返次数，降低延迟并节省 Token 消耗。
全面的文件系统工具集： 提供丰富的文件系统操作工具，包括文件和目录的浏览、内容读写、精确编辑、目录管理、删除、移动、复制以及权限控制等。
易于集成和部署： 可以通过 'npx'/'bunx' 快速集成到 MCP Host 环境，也提供 Docker 镜像方便容器化部署。
参数校验： 所有工具的参数都通过 Zod 进行严格的模式校验，确保请求的有效性。

安装步骤

本服务器提供了多种安装方式，推荐使用 'npx' 或 'bunx' 方式，无需本地安装即可使用最新版本。

1. 使用 'npx' 或 'bunx' (推荐)

这种方式无需本地安装，直接在 MCP Host (如 Roo/Cline) 的配置文件 'mcp_settings.json' 中配置即可。

'npx' 配置示例:

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "npx",
      "args": ["@sylphlab/filesystem-mcp"],
      "name": "Filesystem (npx)"
    }
  }
}

'bunx' 配置示例:

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "bunx",
      "args": ["@sylphlab/filesystem-mcp"],
      "name": "Filesystem (bunx)"
    }
  }
}

重要提示: 请确保你的 MCP Host 配置能够将命令的当前工作目录 ('cwd') 设置为你的项目根目录，这样服务器才能正确访问你的项目文件。

2. 使用 Docker

可以使用官方提供的 Docker 镜像进行容器化部署。

Docker 配置示例:

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/your/project:/app", // 替换为你的项目路径
        "sylphlab/filesystem-mcp:latest"
      ],
      "name": "Filesystem (Docker)"
    }
  }
}

注意: 将 '/path/to/your/project' 替换为你的项目在宿主机上的绝对路径。

3. 本地构建 (开发环境)

克隆仓库: 'git clone https://github.com/sylphlab/filesystem-mcp.git'
进入目录: 'cd filesystem-mcp'
安装依赖: 'pnpm install'
构建项目: 'pnpm run build'

配置 MCP Host:

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "node",
      "args": ["/path/to/cloned/repo/filesystem-mcp/dist/index.js"], // 替换为你的仓库路径
      "name": "Filesystem (Local Build)"
    }
  }
}

注意: 'node' 命令需要在你的项目根目录下执行。

服务器配置

在 MCP 客户端 (如 Roo/Cline) 的配置文件 'mcp_settings.json' 中，你需要配置 'mcpServers' 字段来注册 Filesystem MCP Server。以下是通用的配置结构，你需要根据你的安装方式选择合适的 'command' 和 'args'。

{
  "mcpServers": {
    "filesystem-mcp": {  // server name，客户端通过此名称引用
      "name": "Filesystem", // 在客户端界面上显示的名称，可自定义
      "command": "...",    // 启动服务器的命令，例如 "npx", "bunx", "docker", "node"
      "args": [ ... ]      // 命令参数，根据安装方式和配置生成
    }
  }
}

基本使用方法

配置完成后，你的 AI Agent 就可以通过 MCP 协议调用 Filesystem MCP Server 提供的工具来访问和操作文件系统。例如，使用 'read_content' 工具读取文件内容：

Agent 请求示例 (概念性):
<use_mcp_tool>
  <server_name>filesystem-mcp</server_name>  //  配置中 mcpServers 下的 server name
  <tool_name>read_content</tool_name>      //  要调用的工具名称，例如 read_content, list_files 等
  <arguments>{"paths": ["src/index.ts"]}</arguments> // 工具参数，根据工具定义传递 JSON 格式的参数
</use_mcp_tool>

服务器响应示例:
(src/index.ts 文件的内容)

更多工具的使用方法和参数说明，请参考项目文档 (仓库中 README.md 的 Features 章节详细列出了所有工具及其功能)。

关键词

使用说明

信息