文件系统 MCP 服务器 (@sylphlab/filesystem-mcp)

npm 版本 Docker拉取

**为您的 AI 代理（例如 Cline/Claude）提供安全、高效且节省令牌的项目文件访问权限。**此 Node.js 服务器实现了模型上下文协议 (MCP) ，以提供一套强大的文件系统工具，可在定义的项目根目录中安全运行。

安装

有几种使用文件系统 MCP 服务器的方法：

1. 推荐：通过 MCP 主机配置使用

最简单的方法是通过npx或bunx ，直接在你的 MCP 主机环境中配置（例如，Roo/Cline 的mcp_settings.json ）。这确保你始终使用 npm 的最新版本，而无需本地安装或 Docker。

示例（

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

示例（

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

**重要提示：**服务器使用其自身的当前工作目录 ( cwd ) 作为项目根目录。请确保您的 MCP 主机（例如 Cline/VSCode）已配置为将cwd设置为活动项目的根目录来启动命令。

2. Docker

对于容器化环境，请使用官方 Docker 镜像。

MCP 主机配置示例：

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

请记住用正确的绝对路径替换

3. 本地构建（用于开发）

克隆： git clone https://github.com/sylphlab/filesystem-mcp.git
安装： cd filesystem-mcp && pnpm install （现在使用 pnpm）
构建： pnpm run build
配置 MCP 主机：
{ "mcpServers": { "filesystem-mcp": { "command": "node", "args": ["/path/to/cloned/repo/filesystem-mcp/dist/index.js"], // Updated build dir "name": "Filesystem (Local Build)" } } }
**注意：**从您想要作为项目根目录的目录启动node命令。

Related MCP server: drupal-modules-mcp MCP Server

快速入门

一旦在您的 MCP 主机中配置了服务器（参见安装），您的 AI 代理就可以立即开始使用文件系统工具。

代理交互示例（概念）：

Agent: <use_mcp_tool> <server_name>filesystem-mcp</server_name> <tool_name>read_content</tool_name> <arguments>{"paths": ["src/index.ts"]}</arguments> </use_mcp_tool> Server Response: (Content of src/index.ts)

为什么选择这个项目？

**🛡️ 安全便捷的项目根目录焦点：**操作仅限于项目根目录（启动时为cwd ）。
**⚡ 优化和整合的工具：**批量操作减少了 AI 服务器之间的往返次数，节省了令牌并降低了延迟。批次中每个项目都能获得可靠的结果。
**🚀 轻松集成：**通过npx / bunx快速设置。
**🐳 容器化选项：**以 Docker 镜像形式提供。
**🔧 全面的功能：**涵盖广泛的文件系统任务。
**✅ 稳健验证：**使用 Zod 模式进行参数验证。

性能优势

（占位符：在此处添加基准测试结果和比较，展示相对于单个 shell 命令等替代方法的优势。）

**批量操作：**与单个操作相比，显著减少开销。
**直接使用 API：**比为每个命令生成 shell 进程更有效率。
（如有具体基准数据，请添加）

特征

该服务器为您的 AI 代理配备了强大而高效的文件系统工具包：

📁**探索和检查（ list_files ， stat_items ）：**列出文件/目录（递归，统计），获取多个项目的详细状态。
📄**读取和写入内容（ read_content ， write_content ）：**读取/写入/附加多个文件，创建父目录。
✏️**精确编辑和搜索（ edit_file 、 search_files 、 replace_content ）：**跨多个文件进行外科编辑（插入、替换、删除），并保留缩进和差异输出；带上下文的正则表达式搜索；多文件搜索/替换。
🏗️**管理目录（ create_directories ）：**创建多个目录，包括中间父目录。
🗑️**安全删除（ delete_items ）：**递归删除多个文件/目录。
↔️**移动和复制（ move_items ， copy_items ）：**移动/重命名/复制多个文件/目录。
🔒**控制权限（ chmod_items ， chown_items ）：**更改多个项目的 POSIX 权限和所有权。

**主要优点：**所有接受多条路径/操作的工具都会单独处理每个项目并返回详细的状态报告。

设计理念

（占位符：解释核心设计原则。）

**安全第一：**优先防止项目根目录之外的访问。
**效率：**最大限度地减少 AI 交互的通信开销和令牌使用。
**稳健性：**为批量操作提供详细的结果和错误报告。
**简单性：**通过 MCP 提供清晰一致的 API。
**标准合规性：**严格遵守模型上下文协议。

与其他解决方案的比较

（占位符：客观地与其他选择进行比较。）

特征/方面	文件系统 MCP 服务器	单独的 Shell 命令（通过代理）	其他自定义脚本
安全	高（根受限）	低（代理需要 shell 访问权限）	多变的
效率（代币）	高（批处理）	低（每个操作一个命令）	多变的
延迟	低（直接 API）	高（Shell 生成开销）	多变的
批量操作	是（大多数工具）	不	或许
错误报告	详细（每件）	基本（stdout/stderr 解析）	多变的
设置	简单（npx/Docker）	需要安全外壳设置	风俗

未来计划

（占位符：列出即将推出的功能或改进。）

探索文件监视功能。
调查对超大文件的流式支持。
增强特定操作的性能。
为list_files添加更多高级过滤选项。

文档

（占位符：一旦可用，就添加完整文档网站的链接。）

完整文档（包括详细的 API 参考和示例）可在以下位置获取：[链接至文档站点]

贡献

欢迎贡献！请在GitHub 仓库上创建 issue 或提交 pull request。

执照

该项目根据MIT 许可证发布。

发展

克隆： git clone https://github.com/sylphlab/filesystem-mcp.git
安装： cd filesystem-mcp && pnpm install
构建： pnpm run build （将 TypeScript 编译为dist/ ）
观看： pnpm run dev （可选，保存时重新编译）

发布（通过 GitHub Actions）

此仓库使用 GitHub Actions ( .github/workflows/publish.yml ) 自动将软件包发布到npm ，并在将版本标签 ( v*.*.* ) 推送到main分支时构建/推送 Docker 镜像到Docker Hub 。需要在 GitHub 仓库设置中配置NPM_TOKEN 、 DOCKERHUB_USERNAME和DOCKERHUB_TOKEN密钥。