Filesystem MCP (filesystem-mcp)

文件系统MCP📁

AI代理的安全文件系统操作-通过批处理优化令牌

](https://www.npmjs.com/package/@sylphx/filesystem-mcp) ](https://hub.docker.com/r/sylphx/filesystem-mcp) 

批量操作 • 项目根安全 • 令牌优化 • Zod验证

快速开始 • 安装 • 工具

______________________________________________________________________

🚀 概述

为您的AI代理（如Claude/Cline）提供安全、高效和节省令牌的项目文件访问权限。这个Node.js服务器实现了 模型上下文协议（MCP） 提供一组强大的文件系统工具。

问题：

Traditional AI filesystem access:
- Shell commands for each operation ❌
- No batch processing (high token cost) ❌
- Unsafe (no project root boundaries) ❌
- High latency (shell spawn overhead) ❌

解决方案：

Filesystem MCP Server:
- Batch operations (10+ files at once) ✅
- Token optimized (reduce round trips) ✅
- Secure (confined to project root) ✅
- Direct API (no shell overhead) ✅

结果：为AI代理提供安全、快速和令牌高效的文件系统操作。

______________________________________________________________________

⚡ 性能优势

令牌和延迟优化

现实世界的好处

• 批处理文件读取 -在一个请求中读取10个文件vs 10个请求
• 多文件编辑 -使用单个工具调用编辑多个文件
• 递归操作 -高效地列出整个目录树
• 详细状态 -每项成功/失败报告

______________________________________________________________________

🎯 为什么选择此服务器？

安全与安保

• 🛡️ 项目根限制 -所有操作仅限于 cwd 发射时
• 🔒 权限控制 -内置chmod/chown工具
• ✅ 验证 -Zod模式验证所有参数
• 🚫 路径穿越预防 -无法转义项目目录

效率和性能

• ⚡ 批处理 -每个请求处理多个文件/目录
• 🎯 令牌优化 -减少AI服务器通信开销
• 🚀 直接API -无壳进程生成
• 📊 详细结果 -批处理操作的每个项目状态

开发者体验

• 🔧 简易设置 - npx/bunx 立即使用
• 🐳 Docker就绪 -官方Docker镜像可用
• 📦 综合工具 -11+文件系统操作
• 🔄 MCP标准 -完全符合协议要求

______________________________________________________________________

📦 安装

方法1:npx/bunx（推荐）

最简单的方法-始终使用npm的最新版本。

使用npx：

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

使用bunx：

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "bunx",
      "args": ["@sylphx/filesystem-mcp"],
      "name": "Filesystem (bunx)"
    }
  }
}

重要提示： 服务器使用自己的当前工作目录(cwd)作为项目的根。确保您的MCP主机（例如Cline/VSCode）使用以下命令启动该命令 cwd 设置到项目的根目录。

方法二：Docker

在容器化环境中使用官方Docker镜像。

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

记得更换 /path/to/your/project 根据您的实际项目路径。

方法3：本地建设（开发）

# Clone repository
git clone https://github.com/SylphxAI/filesystem-mcp.git
cd filesystem-mcp

# Install dependencies
pnpm install

# Build
pnpm run build

# Watch mode (auto-rebuild)
pnpm run dev

MCP主机配置：

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "node",
      "args": ["/path/to/filesystem-mcp/dist/index.js"],
      "name": "Filesystem (Local Build)"
    }
  }
}

______________________________________________________________________

🚀 快速开始

在MCP主机中配置后（请参阅安装），您的AI代理可以立即使用文件系统工具。

代理交互示例

  filesystem-mcp
  read_content
  {"paths": ["src/index.ts", "package.json"]}

服务器响应：

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

______________________________________________________________________

📋 特性

文件操作

目录操作

管理操作

权限操作

主要优势： 支持批量操作的工具单独处理每个项目，并返回每个项目的详细状态报告。

______________________________________________________________________

💡 设计理念

核心原则

1. 安全第一

- 所有操作仅限于项目根 - 路径遍历预防 - 内置权限控制

1. 注重效率

- 批处理减少了令牌的使用 - 直接API调用（无shell开销） - 最少的通信往返

1. 鲁棒性

- 每项成功/失败报告 - 详细的错误消息 - Zod模式验证

1. 简洁

- 清晰、一致的API - MCP标准合规性 - 易于集成

______________________________________________________________________

📊 与备选方案的比较

______________________________________________________________________

🛠️ 技术栈

______________________________________________________________________

🎯 用例

AI代理开发

使AI代理能够：

• 读取项目文件 -访问代码、配置、文档
• 编辑多个文件 -跨代码库重构
• 搜索代码库 -查找模式和定义
• 管理项目结构 -创建、移动、组织文件

代码助理

构建强大的编码工具：

• Cline/Claude整合 -直接文件系统访问
• 批量重构 -一次编辑多个文件
• 安全操作 -仅限于项目目录
• 高效运营 -降低代币成本

自动化和脚本

自动化开发任务：

• 文件生成 -创建样板文件
• 项目设置 -初始化目录结构
• 批量处理 -高效处理多个文件
• 内容转换 -跨文件搜索和替换

______________________________________________________________________

🗺️ 路线图

✅ 完成

• \[x\] 核心文件系统操作（读、写、编辑等）
• \[x\] 大多数工具的批处理
• \[x\] 项目根安全
• \[x\] Docker镜像
• \[x\] npm包
• \[x\] Zod验证

🚀 计划的

• \[\]文件监视功能
• \[\]大文件的流媒体支持
• \[\]高级过滤 list_files
• \[\]性能基准
• \[\]压缩/解压缩工具
• \[\]Symlink管理

______________________________________________________________________

🤝 贡献

欢迎投稿！请遵循以下指南：

1. 分叉存储库
2. 创建要素分支 - git checkout -b feature/my-feature
3. 编写测试 -确保良好的覆盖率
4. 遵循TypeScript严格模式 -类型安全第一
5. 添加文档 -必要时更新README
6. 提交拉取请求

开发设置

# Clone and install
git clone https://github.com/SylphxAI/filesystem-mcp.git
cd filesystem-mcp
pnpm install

# Build
pnpm run build

# Watch mode (auto-rebuild)
pnpm run dev

______________________________________________________________________

🤝 支持

](https://www.npmjs.com/package/@sylphx/filesystem-mcp) ](https://github.com/SylphxAI/filesystem-mcp/issues)

• 🐛 错误报告
• 💬 讨论
• 📧 电子邮件

表示支持： ⭐ 明星•👀 观看•🐛 报告错误•💡 建议功能•🔀 贡献

______________________________________________________________________

📄 许可证

MIT© Sylphx

______________________________________________________________________

🙏 学分

内置：

• 模型上下文协议 -MCP标准
• 佐德 -架构验证
• TypeScript -类型安全
• -包管理器

特别感谢MCP社区❤️

______________________________________________________________________

📚 出版

此存储库使用GitHub Actions自动发布到：

• npm: @sylphx/文件系统mcp
• Docker 中心: sylphx/文件系统mcp

在版本标签上触发(v*.*.*)推到 main 支。

所需的秘密: NPM_TOKEN, DOCKERHUB_USERNAME, DOCKERHUB_TOKEN

______________________________________________________________________

Secure. Efficient. Token-optimized.

The filesystem MCP server that saves tokens and keeps your projects safe

sylphx.com • @SylphxAI • hi@sylphx.com