fast-filesystem-mcp

🚀 快速文件系统MCP

快速文件系统MCP为Claude Desktop提供高级文件系统操作，具备处理大文件的能力以及针对Claude优化的特性，能有效提升文件处理效率。

🚀 快速开始

将其添加到你的Claude Desktop配置中。

基础设置

{
  "mcpServers": {
    "fast-filesystem": {
      "command": "npx",
      "args": ["-y", "fast-filesystem-mcp"]
    }
  }
}

启用备份文件

{
  "mcpServers": {
    "fast-filesystem": {
      "command": "npx",
      "args": ["-y", "fast-filesystem-mcp"],
      "env": {
        "CREATE_BACKUP_FILES": "true"
      }
    }
  }
}

备份配置

控制备份文件的创建行为。

• CREATE_BACKUP_FILES=false（默认）：禁用备份文件创建，以减少文件冗余。
• CREATE_BACKUP_FILES=true：在修改文件前创建备份文件。

⚠️ 重要提示

备份文件会带有时间戳（例如，file.txt.backup.1755485284402），以防止在编辑过程中数据丢失。

🆕 新版本更新

要更新到最新版本，请按照以下步骤操作：

1. 卸载旧版本

   npm uninstall -g fast-filesystem-mcp
   

2. 清理缓存和依赖项

   npm cache clean --force
   pnpm store prune
   

3. 安装最新版本

   npm install -g fast-filesystem-mcp
   

4. 验证安装

   npm list -g fast-filesystem-mcp
   fast-filesystem-mcp --version
   

✨ 主要特性

核心文件操作

• 快速文件读写：针对Claude Desktop进行优化，支持分块读写。
• 顺序读取：支持使用延续令牌完整读取大文件。
• 大文件处理：基于流的写入方式，可处理任意大小的文件。
• 目录操作：提供全面的目录列表、创建和管理功能。
• 文件搜索：支持按文件名和内容进行文件搜索，并可进行过滤。

高级功能

• 分页支持：高效处理大型目录。
• 分块读取：以可管理的块读取大文件。
• 流式写入：内存高效的大文件写入方式。
• 备份与恢复：自动创建备份文件并支持错误恢复。
• 重试逻辑：内置重试机制，确保操作可靠。

性能优化

• Claude优化：响应大小和格式针对Claude进行了优化。
• 内存高效：流式操作防止内存溢出。
• 智能排除：自动排除系统文件和目录。
• 进度跟踪：实时监控大型操作的进度。

📦 可用工具

文件操作

| 属性 | 详情 | |------|------| | fast_read_file | 支持分块读取文件 | | fast_read_multiple_files | 支持顺序读取，可同时读取多个文件 | | fast_write_file | 写入或修改文件 | | fast_large_write_file | 基于流的大文件写入 | | fast_get_file_info | 获取详细的文件信息 |

复杂文件管理

| 属性 | 详情 | |------|------| | fast_copy_file | 带有高级选项的文件和目录复制 | | fast_move_file | 安全地移动/重命名文件和目录 | | fast_delete_file | 带有保护机制的文件和目录删除 | | fast_batch_file_operations | 按顺序执行多个文件操作 |

归档管理

| 属性 | 详情 | |------|------| | fast_compress_files | 创建压缩归档文件（tar、tar.gz、tar.bz2） | | fast_extract_archive | 可选择参数提取压缩归档文件 |

目录同步

| 属性 | 详情 | |------|------| | fast_sync_directories | 支持多种模式的高级目录同步 |

高级编辑工具

| 属性 | 详情 | |------|------| | fast_edit_file | 支持多种模式的精确行级文件编辑 | | fast_edit_block | 通过精确字符串匹配进行安全的块编辑 | | fast_edit_blocks | 批量块编辑，实现多个精确更改 | | fast_edit_multiple_blocks | 一次操作中编辑多个部分 | | fast_extract_lines | 从文件中提取特定行或行范围 |

目录操作

| 属性 | 详情 | |------|------| | fast_list_directory | 支持分页的目录内容列表 | | fast_create_directory | 递归创建目录 | | fast_get_directory_tree | 获取目录树结构 |

搜索操作

| 属性 | 详情 | |------|------| | fast_search_files | 按文件名或内容搜索文件 | | fast_search_code | 集成ripgrep的高级代码搜索 | | fast_find_large_files | 在目录中查找大文件 |

系统操作

| 属性 | 详情 | |------|------| | fast_get_disk_usage | 检查磁盘使用信息 | | fast_list_allowed_directories | 列出允许的目录 |

💻 使用示例

精确文件编辑

快速文件系统MCP现在包含用于源代码和文本文件的强大编辑工具。

fast_edit_file - 单块编辑

支持多种编辑模式。

• replace：替换文本或整行。
• replace_range：一次性替换多行。
• insert_before：在指定行之前插入内容。
• insert_after：在指定行之后插入内容。
• delete_line：删除特定行。

{
  "tool": "fast_edit_file",
  "arguments": {
    "path": "/path/to/file.js",
    "mode": "replace",
    "line_number": 10,
    "new_text": "const newVariable = 'updated value';",
    "backup": true
  }
}

fast_edit_multiple_blocks - 批量编辑

在一次操作中编辑文件的多个部分。

{
  "tool": "fast_edit_multiple_blocks", 
  "arguments": {
    "path": "/path/to/file.js",
    "edits": [
      {
        "mode": "replace",
        "old_text": "oldFunction()",
        "new_text": "newFunction()"
      },
      {
        "mode": "insert_after",
        "line_number": 5,
        "new_text": "// Added comment"
      }
    ],
    "backup": true
  }
}

fast_extract_lines - 行提取

按行号、范围或模式提取特定行。

{
  "tool": "fast_extract_lines",
  "arguments": {
    "path": "/path/to/file.js",
    "pattern": "function.*",
    "context_lines": 2
  }
}

fast_search_and_replace - 高级替换

支持正则表达式的强大搜索和替换功能。

{
  "tool": "fast_search_and_replace",
  "arguments": {
    "path": "/path/to/file.js", 
    "search_pattern": "console\\.log\\(.*\\)",
    "replace_text": "logger.info($1)",
    "use_regex": true,
    "max_replacements": 10,
    "backup": true
  }
}

编辑特性

• 自动备份：在修改文件前创建备份。
• 错误恢复：失败时从备份中恢复。
• 行级操作：精确控制特定行。
• 模式匹配：支持正则表达式。
• 批量操作：在单个事务中进行多次编辑。
• 上下文提取：提取带有周围上下文的行。

大文件写入

• fast_large_write_file
  • 流式处理：分块写入文件，防止内存问题。
  • 备份：在覆盖文件前自动创建备份。
  • 验证：写入后验证文件完整性。
  • 重试逻辑：失败时自动重试，采用指数退避策略。
  • 进度跟踪：实时监控写入进度。

📄 许可证

本项目采用Apache 2.0许可证。

版权所有 2025 efforthye

根据Apache许可证，版本2.0（“许可证”）许可；除非符合许可证，否则不得使用此文件。你可以在以下网址获取许可证副本：

除非适用法律要求或书面同意，否则根据许可证分发的软件按“原样”分发，不附带任何形式的明示或暗示保证。请参阅许可证以了解管理权限和限制的特定语言。

🔗 仓库地址

https://github.com/efforthye/fast-filesystem-mcp