Filesystem MCP

Filesystem MCP

让你的 AI 助手安全地处理文件。

读取、搜索、编辑和修补你选择的文件夹中的文件。
机密文件会保持隐藏，有风险的更改则会等待你的确认。

这是什么？

模型上下文协议（MCP）是 Claude、GitHub Copilot in VS Code 和 Cursor 等 AI 应用连接工具的方式。 Filesystem MCP 是一个 MCP 服务：它是在你的计算机上运行的小程序，为 AI 提供 14 个用于处理文件的工具。你可以选择它能访问哪些文件夹，其他所有位置都无法访问。

连接后，你可以提出以下请求：

• “找出此仓库中的所有 TODO，并按文件分组。”
• “将所有 .ts 文件中的 getUser 重命名为 fetchUser。先给我看差异。”
• “config.dev.json 和 config.prod.json 之间有哪些更改？”
• “读取 server.log 的最后 50 行并解释错误。”
• “将旧截图移到 archive/2025/。”

为什么选择 Filesystem MCP？

• 默认安全。AI 只能使用你允许的文件夹，并且会阻止访问 .env 文件、私钥和云凭据。AI 删除非空文件夹、打开未经你允许的文件夹，或使用 create 或 move 覆盖文件前，服务会先征求你的同意。只有 create 和复制操作可以通过传入 overwrite: true 跳过确认。使用 edit、patch 和 replace_text 所做的编辑会直接应用，但你可以先通过 dryRun 查看差异。如果你希望 AI 绝不修改任何内容，--read-only 会移除所有写入工具。
• 专为代码搜索和编辑而设计。AI 可以像使用 grep 一样搜索文件内容，并使用不会卡住的正则表达式引擎（RE2）；默认情况下，服务会跳过 .gitignore 忽略的文件，以及 node_modules 等文件夹。编辑采用精确匹配替换，文本不匹配时会返回错误；你也可以先预览差异。
• 节省 AI 的上下文。AI 可以在一次调用中读取多个文件，也可以只读取所需的行；读取前还可以检查文件大小和令牌估算值。
• 兼容任何 MCP 客户端，可通过 stdio 或 HTTP 运行，支持 macOS、Linux 和 Windows。你可以通过 npx、Docker 或一键安装的 Claude Desktop 扩展来安装，也可以基于它构建自己的客户端。
• 注重隐私。它在你的计算机上运行，不收集遥测数据，也不会发起网络请求。

与参考服务相比

以下是本服务与官方 @modelcontextprotocol/server-filesystem 的区别，依据其 2026-10-11 的 README 核对：

快速开始

说明

你需要 Node.js 24 或更高版本。使用 node --version 查看。

1. 将服务添加到你的 AI 应用。请从下方选择对应的应用。
2. 将 /path/to/project 替换为 AI 可访问的文件夹。你可以列出多个文件夹。
3. 重启应用并询问：“你可以访问哪些文件夹？”

提示

VS Code 目前会将你打开的文件夹共享给服务，因此一键安装到 VS Code 无需指定路径。在其他应用中或通过 HTTP 使用时，请将文件夹填入 args。如果 AI 提示没有可访问的文件夹，这样就能解决。

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
    }
  }
}

code --add-mcp '{"name":"filesystem","command":"npx","args":["-y","@j0hanz/filesystem-mcp@latest","/path/to/project"]}'

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
    }
  }
}

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
    }
  }
}

claude mcp add filesystem -- npx -y @j0hanz/filesystem-mcp@latest /path/to/project

/plugin marketplace add j0hanz/j0hanz-marketplace
/plugin install filesystem-mcp@j0hanz-marketplace

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "C:/path/to/project"]
    }
  }
}

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/project:/workspace:ro",
        "ghcr.io/j0hanz/filesystem-mcp:latest",
        "--read-only",
        "/workspace"
      ]
    }
  }
}

npm install -g @j0hanz/filesystem-mcp

✎ 会更改文件。--read-only 会移除这些工具。

除非 AI 明确要求，否则搜索和列表工具会跳过隐藏文件、被 .gitignore 忽略的文件，以及 node_modules、dist 和 .git 等文件夹。

配置

大多数人只需要提供文件夹参数。以下选项涵盖常见 场景：

标志放在包名称之后的 args 中，例如 ["-y", "@j0hanz/filesystem-mcp@latest", "--read-only", "/path/to/project"]。

完整配置参考涵盖所有标志 和环境变量、完整的机密文件列表、限制、使用 API 密钥的 HTTP 设置、 Docker 和故障排除。

安全

如果你发现安全漏洞，请私下报告。 SECURITY.md 说明了具体方式。

构建自己的客户端

你也可以在自己的代码中调用 Filesystem MCP：例如 Agent、编辑器插件、Web 应用、CI 任务或脚本。规则与 AI 应用相同，因此你的代码无法访问允许文件夹之外的内容，也无法读取机密文件。

import { Client } from '@modelcontextprotocol/client';
import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';

const dir = '/path/to/project';
const client = new Client(
  { name: 'my-app', version: '1.0.0' },
  { capabilities: { elicitation: { form: {} } }, versionNegotiation: { mode: 'auto' } },
);
client.setRequestHandler('elicitation/create', async () => ({ action: 'decline' }));
await client.connect(
  new StdioClientTransport({
    command: 'npx',
    args: ['-y', '@j0hanz/filesystem-mcp', dir],
    cwd: dir,
  }),
);

const result = await client.callTool({ name: 'search_text', arguments: { searchPattern: 'TODO' } });
const { matches } = (result.structuredContent ?? result._meta) as { matches: unknown[] };
console.log(matches);
await client.close(); // stops the server process; without it the script never exits

基本信息：

• 数据所在位置。 文本块是为模型编写的。对于会自行编写文本的工具（list、search_text、edit 等），相同的数据以 JSON 格式存放在 _meta 中；对于 stat、create 和 list_roots，则存放在 structuredContent 中。read 是例外：文件文本仅在文本块中，_meta 中存放的是相关元数据。
• 路径。 如果服务器的工作目录位于某个根目录下，相对路径将相对于该工作目录解析；否则，相对路径将相对于根目录解析。如果有多个根目录，路径必须仅存在于其中一个根目录下。绝对路径不会产生歧义。搜索结果以相对于根目录的路径显示，因此可以直接传回。名称与磁盘上的名称仅在 Unicode 形式（NFC 或 NFD）或空格字符（U+00A0、U+202F）上不同，也能找到对应条目。
• 确认。 覆盖文件、递归删除以及根目录之外的路径都需要向用户确认。声明 elicitation 能力并在处理程序中回答；或者，对于 2026-07-28 协议，将它们作为数据（input_required）接收，稍后再回答。
• 协议版本。 服务器支持 2025 协议和 2026-07-28 协议，可通过 stdio 和 Streamable HTTP 通信。通过 HTTP 通信时，2025 年协议的客户端不会收到确认请求或更改通知。
• 资源。 可通过 filesystem-mcp://file/{+path} 读取和订阅任何文件；internal://instructions 和 get-help 提示词包含面向模型的服务器指南。

客户端指南中有详细说明，并使用 TypeScript 和 Python SDK 进行了测试；examples/ 中有六个可运行的客户端：

隐私政策

Filesystem MCP 完全在你的机器上运行。本政策适用于 npm 包、Docker 镜像和 .mcpb 桌面扩展。

• 数据收集： 无。服务器不进行遥测、分析或崩溃报告，也不会发出任何外部网络请求。
• 使用和存储： 服务器只会在你允许的文件夹内读取和写入文件，且仅在 MCP 客户端调用工具时执行。工具结果只会发送给该客户端，不会发送到其他地方。短期结果缓存和撤销历史记录（保存的文件内容）都存储在内存中，并会在服务器退出时消失。
• 与第三方共享： 服务器不会共享数据。你的 MCP 客户端可能会根据其自身的隐私政策，将工具结果发送给其模型提供商。
• 保留： 进程退出后，服务器不会保留任何内容。诊断日志会写入你机器上的 stderr；你的 MCP 客户端可能会将日志保存到自己的日志文件中。
• 联系方式： 在 https://github.com/j0hanz/filesystem-mcp/issues 提交问题，或通过 GitHub Security Advisories 私下报告安全问题。

参与贡献

欢迎提交 Bug 报告、想法和拉取请求。请先阅读 CONTRIBUTING.md。其中介绍了环境配置、从源代码运行服务，以及拉取请求需要通过的检查。

如果 Filesystem MCP 对你有帮助，请在 GitHub 上点个星，帮助更多人发现它。

许可证

MIT