文件系统MCP服务器

面向AI代理的安全文件操作

官方MCP参考实现，提供具备细粒度权限控制的安全沙盒化文件系统访问

为何选择文件系统MCP？

🔒 安全优先设计

• 沙盒化访问：代理仅能访问明确授权的目录
• 权限控制：按目录设置只读、写入或完全访问权限
• 路径验证：防止目录遍历和未经授权的访问
• 审计追踪：记录所有操作以供安全审查

🤖 代理工作流的核心需求

大多数代理任务涉及文件操作：

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

📦 零外部依赖

仅使用 Node.js 内置模块的纯实现。无外部 API 依赖或速率限制。

安装

# Official reference implementation
npm install -g @modelcontextprotocol/server-filesystem

# Or build from source
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: "What files are in my Projects folder?"
Agent: "Show contents of /workspace/src"

返回：

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

2.创建目录(create_directory)

Agent: "Create a new folder called 'components'"
Agent: "Make directory /workspace/tests"

3.移动/重命名(move_file)

Agent: "Rename old-name.txt to new-name.txt"
Agent: "Move report.pdf to /Documents/Reports/"

文件操作

4.读取文件(read_file)

Agent: "Read the contents of config.json"
Agent: "Show me the README.md file"

支持：

• 文本文件 (UTF-8)
• JSON、YAML、XML
• Markdown、代码文件
• 大型文件（流式处理）

5.写入文件(write_file)

Agent: "Create a file called notes.txt with meeting notes"
Agent: "Write the generated code to src/index.ts"

6.编辑文件(edit_file)

Agent: "Replace 'version: 1.0' with 'version: 2.0' in package.json"
Agent: "Add a new function to utils.js"

7.获取文件信息(get_file_info)

Agent: "When was report.pdf last modified?"
Agent: "What's the size of data.csv?"

返回：

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

高级操作

8.搜索文件(search_files)

Agent: "Find all Python files in the project"
Agent: "Search for files containing 'API_KEY'"

搜索依据：

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

9.删除文件(delete_file)

Agent: "Delete the temporary log files"
Agent: "Remove old-backup.zip"

安全性:

• 删除大文件需要确认
• 无法删除允许目录外的文件
• 操作记录用于审计

代理工作流示例

代码生成

Human: "Create a React component for a login form"

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. "Created LoginForm component at components/LoginForm.tsx"

日志分析

Human: "Analyze error logs and summarize issues"

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: "Organize my documents by type"

Agent:
1. list_directory("/Documents")
2. For each file:
   - get_file_info(file)
   - Determine file type
   - create_directory("/Documents/[type]")
   - move_file(file, destination_folder)

文档生成

Human: "Generate API documentation from code comments"

Agent:
1. search_files(pattern="*.ts", path="/src")
2. For each file:
   - read_file(file)
   - extract_doc_comments()
3. Generate markdown docs
4. write_file("/docs/API.md", generated_docs)

安全模型

沙盒执行

代理可以执行的操作：

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

代理无法执行的操作：

• ❌ 访问父级目录../)
• ❌ 访问系统文件 (/etc/,/sys/)
• ❌ 跟踪允许路径外的符号链接
• ❌ 执行二进制文件或脚本
• ❌ 修改文件权限

路径验证

Allowed: /Users/dev/projects
Agent tries: /Users/dev/projects/src/index.ts → ✅ Allowed
Agent tries: /Users/dev/projects/../secret → ❌ Blocked
Agent tries: /etc/passwd → ❌ Blocked

最佳实践

1. 最小权限原则

   • 仅授予必要的目录
   • 当不需要写入时，使用--read-only选项

2. 绝不允行根目录访问

   • 不要添加/或系统目录
   • 限制在用户工作区内

3. 审计代理操作

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

4. 隔离敏感数据

   • 将凭据、密钥保存在独立目录中
   • 不包含在允许的路径中

使用案例

📝 内容管理

智能体生成博客文章、报告、文档并保存至组织有序的文件夹

🤖 代码助手

读取项目文件、生成代码、创建测试、更新配置

📊 数据分析

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

🗂️ 文件整理

扫描目录、分类文件、移至对应文件夹、清理重复内容

📚 知识库

索引Markdown文件、检索文档、提取信息、更新维基

🔍 日志分析

解析日志文件、识别错误、生成摘要、创建告警

性能表现

大文件处理

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

目录扫描

• 优化递归搜索
• 通配符模式匹配
• 忽略模式（例如：node_modules/）

并发操作

• 支持并行文件访问
• 原子写操作
• 需要时进行文件锁定

故障排除

"权限被拒绝"错误

• 验证路径是否在允许的目录中
• 检查文件系统权限
• 确保MCP服务器具有读写权限

"路径未找到"错误

• 确认目录存在
• 检查路径拼写错误
• 验证路径格式（绝对路径与相对路径）

只读模式问题

• 无法在--只读模式下写入
• 如有需要，请重新配置服务器以启用写入权限

与其他文件访问方式的对比

资源

• 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 是智能体文件操作的基础。