文件系统 MCP 服务器

面向 AI 智能体的安全文件操作

官方 MCP 参考实现，提供安全、沙箱化的文件系统访问能力，并支持细粒度的权限控制。

为何选择文件系统 MCP？

🔒 以安全为先的设计

• 沙箱化访问：智能体仅可访问显式授权的目录
• 权限控制：按目录分别配置只读、写入或完全访问权限
• 路径校验：防止目录遍历攻击及未授权访问
• 审计日志：所有操作均被记录，便于安全审查

🤖 智能体工作流的关键依赖

大多数智能体任务均涉及文件操作：

• 读取文档资料
• 编写代码文件
• 分析日志内容
• 生成报告
• 管理项目文件
• 整理内容资源

📦 零外部依赖

纯 Node.js 实现，仅使用内置模块，不依赖任何外部 API，亦无调用频率限制。

安装

# 官方参考实现
npm install -g @modelcontextprotocol/server-filesystem

# 或从源码构建
git clone https://github.com/modelcontextprotocol/servers
cd servers/src/filesystem
npm install
npm run build

配置

在您的 MCP 客户端配置中添加以下内容：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/Documents",
        "/Users/yourname/Projects"
      ]
    }
  }
}

参数 = 允许访问的目录（一个或多个绝对路径）

权限模式

只读访问：

"args": ["--read-only", "/path/to/docs"]

完全访问（默认）：

"args": ["/path/to/workspace"]

配置示例

开发工作区

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/dev/projects",
        "/Users/dev/workspace"
      ]
    }
  }
}

文档访问（只读）

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "--read-only",
        "/Users/docs/knowledge-base"
      ]
    }
  }
}

可用工具

目录操作

1. 列出目录内容（list_directory）

智能体：“我的 Projects 文件夹里有哪些文件？”
智能体：“显示 /workspace/src 下的内容”

返回结果包含：

• 文件名
• 文件类型（普通文件、目录、符号链接）
• 文件大小
• 最后修改时间戳

2. 创建目录（create_directory）

智能体：“新建一个名为 ‘components’ 的文件夹”
智能体：“在 /workspace/tests 路径下创建目录”

3. 移动/重命名（move_file）

智能体：“将 old-name.txt 重命名为 new-name.txt”
智能体：“将 report.pdf 移动至 /Documents/Reports/ 目录下”

文件操作

4. 读取文件（read_file）

智能体：“读取 config.json 的内容”
智能体：“展示 README.md 文件内容”

支持格式：

• 文本文件（UTF-8 编码）
• JSON、YAML、XML
• Markdown、各类源代码文件
• 大文件（支持流式读取）

5. 写入文件（write_file）

智能体：“创建名为 notes.txt 的文件并写入会议纪要”
智能体：“将生成的代码写入 src/index.ts”

6. 编辑文件（edit_file）

智能体：“在 package.json 中将 ‘version: 1.0’ 替换为 ‘version: 2.0’”
智能体：“向 utils.js 中添加一个新函数”

7. 获取文件信息（get_file_info）

智能体：“report.pdf 最后一次修改是什么时候？”
智能体：“data.csv 的大小是多少？”

返回结果包含：

• 文件大小（字节）
• 创建时间
• 最后修改时间
• 权限信息
• 文件类型

高级操作

8. 搜索文件（search_files）

智能体：“查找项目中所有的 Python 文件”
智能体：“搜索包含 ‘API_KEY’ 字符串的文件”

支持按以下条件搜索：

• 文件名模式（glob 通配）
• 文件内容（正则表达式匹配）
• 文件类型
• 最后修改日期

9. 删除文件（delete_file）

智能体：“删除临时日志文件”
智能体：“移除 old-backup.zip”

安全性保障：

• 对大文件执行删除操作前需二次确认
• 无法删除允许目录范围之外的文件
• 所有删除操作均被记录用于审计

智能体工作流示例

代码生成

用户：“创建一个 React 登录表单组件”

智能体：
1. create_directory("/workspace/components")
2. write_file("/workspace/components/LoginForm.tsx", generated_code)
3. write_file("/workspace/components/LoginForm.test.tsx", test_code)
4. “已在 components/LoginForm.tsx 创建 LoginForm 组件”

日志分析

用户：“分析错误日志并汇总问题”

智能体：
1. list_directory("/var/log/app")
2. read_file("/var/log/app/error.log")
3. search_files(pattern="ERROR", path="/var/log/app")
4. generate_summary()
5. write_file("/reports/error-summary.md", summary)

项目组织

用户：“按类型整理我的文档”

智能体：
1. list_directory("/Documents")
2. 对每个文件：
   - get_file_info(file)
   - 判定文件类型
   - create_directory("/Documents/[type]")
   - move_file(file, destination_folder)

文档生成

用户：“根据代码注释生成 API 文档”

智能体：
1. search_files(pattern="*.ts", path="/src")
2. 对每个文件：
   - read_file(file)
   - extract_doc_comments()
3. 生成 Markdown 格式文档
4. write_file("/docs/API.md", generated_docs)

安全模型

沙箱强制执行

智能体可以执行的操作：

• ✅ 访问显式授权的目录
• ✅ 在授权路径内创建、读取、写入文件
• ✅ 列出目录内容
• ✅ 在授权路径内执行搜索

智能体不可执行的操作：

• ❌ 访问父级目录（如 ../）
• ❌ 访问系统文件（如 /etc/、/sys/）
• ❌ 跟随指向授权路径外的符号链接
• ❌ 执行二进制文件或脚本
• ❌ 修改文件权限

路径校验

授权路径：/Users/dev/projects
智能体请求：/Users/dev/projects/src/index.ts → ✅ 允许
智能体请求：/Users/dev/projects/../secret → ❌ 拦截
智能体请求：/etc/passwd → ❌ 拦截

最佳实践

1. 最小权限原则

   • 仅授予必要目录的访问权限
   • 无需写入时，务必使用 --read-only 参数

2. 切勿授予根目录访问权限

   • 禁止添加 / 或其他系统级目录
   • 严格限定于用户工作区路径

3. 定期审计智能体行为

   • 定期查阅 MCP 服务器日志
   • 监控异常的文件访问模式

4. 敏感数据隔离

   • 将凭证、密钥等存放于独立目录
   • 切勿将其纳入授权路径中

典型应用场景

📝 内容管理

智能体自动生成博客文章、报告、技术文档，并分类保存至结构化文件夹中。

🤖 代码辅助

读取项目源码，生成新代码，编写测试用例，更新配置文件等。

📊 数据分析

读取 CSV/JSON 等数据文件，执行分析，生成报告与可视化图表。

🗂️ 文件整理

扫描目录，自动识别并归类文件，迁移至对应文件夹，并清理重复项。

📚 知识库管理

索引 Markdown 文档，全文检索技术资料，抽取关键信息，自动更新 Wiki。

🔍 日志分析

解析日志文件，识别错误模式，生成摘要报告，并触发告警机制。

性能表现

大文件处理

• 大于 10MB 的文件启用流式读取
• 支持增量式读取
• 内存占用低，处理高效

目录扫描

• 递归搜索经过性能优化
• 支持 glob 模式匹配
• 支持忽略规则（例如 node_modules/）

并发操作

• 支持安全的并行文件访问
• 写入操作具备原子性
• 按需启用文件锁机制

故障排查

“Permission denied”（权限拒绝）错误

• 确认请求路径是否在已授权目录列表中
• 检查操作系统层面的文件系统权限
• 确保 MCP 服务器进程拥有对应路径的读写权限

“Path not found”（路径未找到）错误

• 确认目标目录实际存在
• 检查路径是否存在拼写错误
• 确认路径格式（必须为绝对路径，不支持相对路径）

只读模式相关问题

• 启用 --read-only 后无法执行写入操作
• 如需写入能力，请重新配置服务器并授予相应权限

与其他文件访问方式对比

参考资料

• GitHub 仓库: https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem
• MCP 官方文档: https://modelcontextprotocol.io/
• 安全最佳实践指南: https://modelcontextprotocol.io/docs/concepts/security

高级配置

{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": [
        "/path/to/filesystem-server/build/index.js",
        "/workspace",
        "/documents"
      ],
      "env": {
        "MAX_FILE_SIZE": "10485760",
        "ENABLE_LOGGING": "true",
        "LOG_PATH": "/var/log/mcp-filesystem.log"
      }
    }
  }
}

面向智能体的安全、可靠文件系统访问能力：从代码生成到日志分析，文件系统 MCP 是智能体执行文件操作的核心基础设施。