/ 目录 / 演练场 / Filesystem
● 官方 modelcontextprotocol ⚡ 即开即用

Filesystem

作者 modelcontextprotocol · modelcontextprotocol/servers

给 Claude 一个沙箱化的目录读写权限——重构代码、处理文档、分析日志,无需切换到 shell。

官方参考实现的 Filesystem MCP。将一个或多个目录挂载为根路径,每次工具调用都被严格限制在这些根目录内,Claude 无法通过 ../ 访问你的 SSH 密钥。支持文本、二进制、搜索和行级编辑。装机量最高的 MCP,名副其实。

为什么要用

核心特性

实时演示

实际使用效果

filesystem.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/workspace"
      ]
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/workspace"
      ]
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/workspace"
      ]
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标,然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/workspace"
      ]
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "filesystem",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/workspace"
      ]
    }
  ]
}

Continue 使用服务器对象数组,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "filesystem": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-filesystem",
          "/workspace"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /workspace

一行命令搞定。用 claude mcp list 验证,claude mcp remove 卸载。

使用场景

实战用法: Filesystem

如何在整个代码库中重构一个函数而不把它搞坏

👤 需要重命名或改造被多文件引用的 API 的工程师 ⏱ ~20 min intermediate

何时使用: 你要重命名一个函数、改变签名或内联一个 helper——而它被仓库中 30+ 个文件使用。

前置条件
  • 干净的 git 工作区git status 无暂存项——这样你可以 git diff 审查,必要时 git restore 回滚
  • Filesystem 根路径限定在该仓库 — 用 npx -y @modelcontextprotocol/server-filesystem /abs/path/to/repo 启动
步骤
  1. 找到所有调用点
    在代码库中搜索所有 getUserProfile( 的使用。按文件分组匹配项,并给出每个文件的命中数。✓ 已复制
    → 文件列表加命中数,能区分测试与源码
  2. 在单个文件上试运行编辑
    告诉我在 src/api/users.ts 里编辑长什么样——给 diff,不要整个文件。先别写入。✓ 已复制
    → 最小 diff 补丁,而不是整文件重写
  3. 应用到所有文件并汇报
    把同样的变换应用到第 1 步列出的每个文件。用 edit_file(行级)而不是 write_file(覆盖)。告诉我哪些文件的模式没有干净匹配。✓ 已复制
    → 逐文件的成功/跳过日志

结果: 一份聚焦、可审查的 git diff,你能直接跑测试——不会出现意外的整文件重写。

注意事项
  • 当编辑复杂时,Claude 用 write_file 并悄悄丢掉半个文件 — 明确要求对原位修改用 edit_file;只有新建文件才允许 write_file
  • 匹配命中无关代码(如 getUserProfileAvatar — 锚定搜索:带尾括号的 getUserProfile(,或使用词边界正则
搭配使用: git · github

通过本地读取生产日志文件来排查崩溃

👤 磁盘上有日志的 on-call 工程师 ⏱ ~15 min beginner

何时使用: 你刚从客户工单下载了一个日志包,需要在不用 grep 黑魔法的情况下大海捞针。

前置条件
  • 日志已在磁盘上 — 下载并解压到专用的 /incidents/<ticket>/ 目录
步骤
  1. 先拿到结构性概览
    列出 /incidents/TICKET-1234/ 下的所有文件。对每个日志文件,给出大小以及内部的首末时间戳。✓ 已复制
    → 带时间区间的清单
  2. 定位错误聚集段
    在所有 .log 文件里搜索模式 ERROR|FATAL|panic。告诉我命中密度最高的 10 分钟窗口。✓ 已复制
    → 时间窗口收窄到分钟级,而不是小时级
  3. 读取首个 fatal 周围的上下文
    读取 app.log 中第一条 FATAL 行前后 50 行上下文。解释系统在崩溃前正在做什么。✓ 已复制
    → 叙事性重建,而不是堆砌日志

结果: 一段 5 句话的时间线,可以直接贴进事故文档。

注意事项
  • 大日志文件(>50MB)会炸掉模型上下文 — 只要求 head/tail + grep 式提取;永远不要让 Claude 对大文件做‘读整个文件’
搭配使用: sentry · github

向一个装满 PDF、Markdown 和文档的文件夹提问

👤 手里攒了一堆参考资料的研究员、分析师 ⏱ ~15 min beginner

何时使用: 你有 50 份论文/合同/报告在一个文件夹里,要抽取某个具体事实或跨文档对比。

前置条件
  • 文档集中在一个文件夹 — 展平到单一目录或浅层树;Claude 在扁平结构上遍历更好
步骤
  1. 为文件夹建索引
    列出 /research/2026-market-study/ 下的每个文件。对每个文件,给出文件名和前 200 个字符。✓ 已复制
    → 带快速预览的清单
  2. 问真正的问题
    这些文档中哪些提到了 'contractual indemnity cap'?对每个命中,引用确切的句子并给出文件名。✓ 已复制
    → 带文件名的引用,而不是凭感觉
  3. 跨文档综合
    对比 3 份文档中提到的 indemnity cap。哪份对我方最有利,为什么?✓ 已复制
    → 并排对比并带直接引用

结果: 带文件名+引用的答案,30 秒内可验证。

注意事项
  • 扫描版 PDF 是图像——内容搜索会失败 — 先跑 OCR(如 ocrmypdf)或使用专用 PDF MCP;开始前先标记出‘不可搜索’的文件
  • Claude 做总结时丢失出处 — 始终在提示词中要求 文件名 + 精确引用;没有的话就拒绝答案
搭配使用: memory

一轮对话从一段规格生成新项目骨架

👤 正在开启新 service/lib/原型的工程师 ⏱ ~10 min beginner

何时使用: 你有一段话的规格,想把样板(目录、package.json、README、测试)直接落地,不用从模板仓库复制。

前置条件
  • 空的目标目录mkdir /projects/newthing,将 filesystem 根指向它的父目录
步骤
  1. 写入前先确定布局
    我想要一个做 X 的 TypeScript Node CLI 工具。提议目录结构,列出你会创建的每个文件并用一行说明用途。先别写入。✓ 已复制
    → 逐文件的计划——你在动磁盘之前可以否决
  2. 写入文件
    看起来不错。把这些文件全部创建在 /projects/newthing/ 下。内容要精简、惯用——不要占位注释,不要 'TODO' 空壳。✓ 已复制
    → 文件落盘,首轮就能通过编译/lint
  3. 回读验证
    把你刚创建的每个文件都读一遍,确认项目能通过 tsc --noEmitnpm test。不行就修。✓ 已复制
    → 自检并给出具体修复,而不是打哈哈

结果: 3 分钟搞定一个可跑的骨架项目,而不是 30 分钟。

注意事项
  • Claude 写了文件又在会话中途忘了自己写过什么 — 先产出文件计划再写;结尾回读能捕捉漂移
搭配使用: git · github

组合

与其他 MCP 搭配,撬动十倍杠杆

filesystem + github

在本地编辑文件,push 一个分支并开 PR,不离开对话

修复 src/utils/format.ts:42 的 typo,然后 push 一个新分支 fix/typo-format,开一个标题为 'fix: typo in format.ts' 的 PR。✓ 已复制
filesystem + git

做编辑、审阅 diff、提交——全程在 Claude 里

把 src/ 里 3 个重复的 helper 重构成一个共享 util。提交前先让我看 diff,然后用干净的 message 提交。✓ 已复制
filesystem + sqlite

从磁盘读 CSV,加载到 SQLite 表中做分析

读取 /data/orders.csv,推断类型,把它作为表 orders 加载到 /data/analysis.db。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
read_text_file path: str, head?: int, tail?: int 读取文本文件;用 head/tail 避免加载巨大文件 free
read_media_file path: str 以 base64 形式读取图片、PDF、音频作为多模态输入 free
read_multiple_files paths: str[] 一轮内批量读取相关文件(比 N 次调用更快) free
write_file path: str, content: str 创建新文件或整体覆盖——破坏性 free
edit_file path: str, edits: [{oldText, newText}], dryRun?: bool 更安全的行级编辑;对已存在文件始终优先使用,不要用 write_file free
create_directory path: str 创建目录(递归,mkdir -p 风格) free
list_directory path: str 非递归 ls free
directory_tree path: str 一眼看到项目结构概览 free
move_file source: str, destination: str 重命名或移动 free
search_files path: str, pattern: str, excludePatterns?: str[] 递归内容搜索——类似 grep free
get_file_info path: str 不读取内容仅 stat 一个文件 free
list_allowed_directories none 确认服务器启动时配置了哪些根目录 free

成本与限制

运行它的成本

API 配额
无限——本地 I/O
每次调用 Token 数
取决于文件大小——按每 4 个字符约 1 token 估算
费用
免费
提示
优先用 search_fileshead/tail,而不是读整个文件。一个 2MB 日志扔进上下文要耗约 50 万 token。

安全

权限、密钥、影响范围

最小权限: filesystem-read filesystem-write (if mutating)
凭据存储: 无凭据——访问通过作为参数传入的根目录实现
数据出站: 服务器自身无数据外发——文件内容通过 MCP 客户端作为上下文发往你的 LLM 服务商
切勿授予: root=/ root=$HOME root=/etc or /var

故障排查

常见错误与修复

Error: Path is not within allowed directories

文件不在启动时配置的任何根目录内。带上额外的根参数重启服务器,或用 list_allowed_directories 查看实际允许的范围。

验证: 让 Claude 调用 `list_allowed_directories`
ENOENT: no such file or directory

路径拼错或者对工作目录的假设错了。在根上用 directory_tree 看看真实布局。

edit_file: oldText not found

oldText 模式必须包含空白在内精确匹配。让 Claude 先 read_text_file 再复制精确子串。

巨型文件冻住客户端

不要读超过几 MB 的整文件。用 read_text_filehead/tail 参数,或 search_files 只抓相关行。

验证: 先用 `get_file_info` 查文件大小

替代方案

Filesystem 对比其他方案

替代方案何时用它替代权衡
git MCP你需要版本感知操作(diff、blame、log),而不是原始文件 I/O没有写工具;只透过 git 视角只读
GitHub MCP文件在远程仓库,你不想本地 clone需要 PAT;每文件延迟远高于本地磁盘
JetBrains MCP你希望编辑出现在正在运行的 IDE 实例中,并利用重构工具需要打开 JetBrains IDE;比纯 filesystem 重得多

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills