Filesystem MCP Server

AI Agent 的安全文件操作

官方 MCP 参考实现，提供经过沙箱隔离的文件系统访问能力，支持细粒度权限控制。

为什么需要 Filesystem MCP？

🔒 安全优先的设计

• 沙箱化访问：Agent 只能访问明确允许的目录
• 权限控制：每个目录可配置只读、写入或完全访问权限
• 路径验证：防止目录遍历和未授权访问
• 审计日志：所有操作均被记录，便于安全审查

🤖 对 Agent 工作流至关重要

大多数 Agent 任务都涉及文件操作：

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

📦 无外部依赖

纯使用 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)

Agent: "我的 Projects 文件夹里有哪些文件？"
Agent: "显示 /workspace/src 的内容"

返回信息：

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

2. 创建目录 (create_directory)

Agent: "创建一个名为 'components' 的新文件夹"
Agent: "在 /workspace/tests 创建目录"

3. 移动/重命名文件 (move_file)

Agent: "将 old-name.txt 重命名为 new-name.txt"
Agent: "把 report.pdf 移动到 /Documents/Reports/"

文件操作

4. 读取文件 (read_file)

Agent: "读取 config.json 的内容"
Agent: "给我看看 README.md 文件"

支持格式：

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

5. 写入文件 (write_file)

Agent: "创建一个名为 notes.txt 的文件，内容为会议笔记"
Agent: "将生成的代码写入 src/index.ts"

6. 编辑文件 (edit_file)

Agent: "将 package.json 中的 'version: 1.0' 替换为 'version: 2.0'"
Agent: "在 utils.js 中添加一个新函数"

7. 获取文件信息 (get_file_info)

Agent: "report.pdf 上次修改是什么时候？"
Agent: "data.csv 的大小是多少？"

返回信息：

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

高级操作

8. 搜索文件 (search_files)

Agent: "在项目中查找所有 Python 文件"
Agent: "搜索包含 'API_KEY' 的文件"

支持搜索条件：

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

9. 删除文件 (delete_file)

Agent: "删除临时日志文件"
Agent: "移除 old-backup.zip"

安全机制：

• 删除大文件前需确认
• 无法删除允许路径之外的文件
• 所有操作均记录在审计日志中

Agent 工作流示例

代码生成

Human: "创建一个用于登录表单的 React 组件"

Agent:
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 组件"

日志分析

Human: "分析错误日志并总结问题"

Agent:
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)

项目整理

Human: "按类型整理我的文档"

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

文档生成

Human: "根据代码注释生成 API 文档"

Agent:
1. search_files(pattern="*.ts", path="/src")
2. 对每个文件：
   - read_file(file)
   - 提取文档注释
3. 生成 Markdown 文档
4. write_file("/docs/API.md", generated_docs)

安全模型

沙箱强制执行

Agent 可以执行的操作：

• ✅ 访问明确允许的目录
• ✅ 在允许路径内创建、读取、写入文件
• ✅ 列出目录内容
• ✅ 在允许路径内进行搜索

Agent 不可执行的操作：

• ❌ 访问父目录（../）
• ❌ 访问系统文件（/etc/、/sys/）
• ❌ 跟随超出允许路径的符号链接
• ❌ 执行二进制文件或脚本
• ❌ 修改文件权限

路径验证

允许路径：/Users/dev/projects
Agent 尝试访问：/Users/dev/projects/src/index.ts → ✅ 允许
Agent 尝试访问：/Users/dev/projects/../secret → ❌ 阻止
Agent 尝试访问：/etc/passwd → ❌ 阻止

最佳实践

1. 最小权限原则

- 仅授予必要的目录

- 无需写入时使用 --read-only 参数

1. 禁止根目录访问

- 不要添加 / 或系统目录

- 限制在用户工作区范围内

1. 审计代理行为

- 定期审查 MCP 服务器日志

- 监控异常文件访问模式

1. 敏感数据隔离

- 将凭证、密钥等存放在独立目录

- 不将其包含在允许的路径中

使用场景

📝 内容管理

代理生成博客文章、报告、文档，并保存至结构化文件夹。

🤖 代码助手

读取项目文件，生成代码，创建测试用例，更新配置。

📊 数据分析

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

🗂️ 文件整理

扫描目录，分类文件，移动至合适位置，清理重复项。

📚 知识库构建

索引 Markdown 文件，搜索文档，提取信息，更新维基内容。

🔍 日志分析

解析日志文件，识别错误，生成摘要，创建告警通知。

性能表现

大文件处理

• 文件大于 10MB 时支持流式传输
• 支持增量读取
• 内存高效处理

目录扫描

• 递归搜索已优化
• 支持通配符模式匹配（Glob）
• 可配置忽略模式（如 node_modules/）

并发操作

• 支持并行文件访问
• 写入操作为原子性
• 必要时启用文件锁机制

故障排查

“权限不足”错误

• 确认路径在允许的目录范围内
• 检查文件系统权限
• 确保 MCP 服务具备读写权限

“路径未找到”错误

• 确认目录是否存在
• 检查路径拼写是否正确
• 验证路径格式（绝对路径或相对路径）

只读模式问题

• --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"
      }
    }
  }
}

安全可靠的代理文件系统访问方案：从代码生成到日志分析，Filesystem MCP 是代理文件操作的基础。