Filesystem MCP Server (@sylphlab/filesystem-mcp)

Filesystem MCP

你的 Agent 操作了代码仓库。它还在项目里吗？

为 AI Agent 提供安全、节省 token 的文件系统操作——批量读取、精准编辑，并将操作限制在项目根目录内，无需承受启动 shell 的开销。

批量操作 · 项目根目录安全 · Zod 验证 · 13 个 MCP 工具 · 支持 Docker

⭐ 为此仓库点星，让 Agent 能安全地读取和编辑你的代码库，而不是为每个文件都启动 shell。 · 快速开始 · 查看运行效果 · 为什么不用 shell 命令？ · 路线图

问题所在

Agent 需要访问文件系统，才能读取代码、应用编辑并搜索代码仓库。默认方式是使用shell 命令——每项操作都要启动一次进程，无法批量处理，还要解析 stderr，并且路径可能超出项目范围。

这会消耗 token、增加延迟，还会让每次文件操作都变成一次信任考验。

Filesystem MCP 专为 Agent 需要快速、受限且便于批量处理的文件操作而打造，所有操作都限制在项目根目录内。

为什么不用 shell 命令？

完整的基准测试说明：docs/benchmark.md。

查看运行效果

配置一次，即可在一次调用中读取多个文件。

claude mcp add filesystem -- npx @sylphx/filesystem-mcp

{
  "paths": ["src/index.ts", "package.json", "README.md"]
}

read_content 会在一次响应中返回每个文件的结果：

{
  "results": [
    { "path": "src/index.ts", "content": "...", "success": true },
    { "path": "package.json", "content": "...", "success": true },
    { "path": "README.md", "content": "...", "success": true }
  ]
}

**重要：**启动 MCP 服务时，请将 cwd 设置为项目根目录。所有路径都相对于该目录。

Agent 为什么会使用它

快速开始

Claude Code

claude mcp add filesystem -- npx @sylphx/filesystem-mcp

请从项目目录运行，以便 cwd 指向仓库根目录。

Claude Desktop／任何 MCP 主机

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "npx",
      "args": ["@sylphx/filesystem-mcp"]
    }
  }
}

将主机的工作目录设为项目根目录。

Docker

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/path/to/your/project:/app",
        "sylphx/filesystem-mcp:latest"
      ]
    }
  }
}

本地开发

git clone https://github.com/SylphxAI/filesystem-mcp.git
cd filesystem-mcp
bun install
bun run build
bun run test

MCP 工具一览

发布验证

相关声明由 CI benchmark:release-gate、安全测试语料库和已发布路径矩阵（主要工具默认使用 Rust）提供支持。

bun run benchmark:release-gate

构件：benchmark-artifacts/filesystem_release_gate.json — 发布前必须报告 status: passed。

性能基准测试

在已发布的 Rust CLI 路径上复现本地吞吐量：

bunx vitest bench __tests__/benchmarks/throughput.bench.ts --run

有关测试场景、设计目标以及结果解读方法，请参阅 docs/benchmark.md。

安全模型

• 所有操作都限制在服务启动时的 cwd 中。
• 拒绝绝对路径；阻止路径遍历。
• Zod 模式会验证每个工具参数。
• 批处理工具会返回逐项状态 — 一项失败不会掩盖其余结果。

文档

开发

bun run validate    # lint + typecheck + test
bun run docs:build  # VitePress + API docs
bun run benchmark   # vitest bench

支持

• 问题反馈
• 讨论区
• npm 软件包

帮助更多开发者发现这个项目

如果按文件调用 shell 的 Agent 工作流耗费了你的 token，或让你对路径安全失去信心，那么这个项目正适合你。

⭐ 为仓库点星 — 这有助于更多 Agent 构建者找到安全、适合批处理的文件系统访问方式。

收录情况（进行中）

知道其他 MCP 目录吗？请通过 提交问题 告知我们链接。

许可证

MIT © Sylphx