MCP Filesystem

🚀 MCP文件系统服务器

MCP文件系统服务器是一个强大的模型上下文协议（MCP）服务器，专为文件系统操作而设计，尤其适用于与大型文件和文件系统进行智能交互。它通过智能上下文管理，为文件和目录提供安全访问，在处理大量数据时可最大程度提高效率。

🚀 快速开始

1. 克隆并设置

首先，若尚未安装uv，请进行安装：

# 使用官方安装程序安装uv
curl -fsSL https://raw.githubusercontent.com/astral-sh/uv/main/install.sh | bash

# 或者使用pipx安装
pipx install uv

然后克隆仓库并安装依赖项：

# 克隆仓库
git clone https://github.com/safurrier/mcp-filesystem.git
cd mcp-filesystem

# 使用uv安装依赖项
uv pip sync requirements.txt requirements-dev.txt

2. 获取绝对路径

你需要获取仓库位置以及想要访问的任何目录的绝对路径：

# 获取仓库的绝对路径
REPO_PATH=$(pwd)
echo "仓库路径: $REPO_PATH"

# 获取想要访问的目录的绝对路径
realpath ~/Documents
realpath ~/Downloads
# 或者在没有realpath的系统上：
echo "$(cd ~/Documents && pwd)"

3. 配置Claude桌面版

打开Claude桌面版配置文件：

• 在macOS上：~/Library/Application\ Support/Claude/claude_desktop_config.json
• 在Windows上：%APPDATA%/Claude/claude_desktop_config.json

添加以下配置（替换为你实际的路径）：

{
  "mcpServers": {
    "mcp-filesystem": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-filesystem",
        "run",
        "run_server.py",
        "/absolute/path/to/dir1",
        "/absolute/path/to/dir2"
      ]
    }
  }
}

⚠️ 重要提示

所有路径必须是绝对路径（从根目录开始的完整路径）。请使用realpath或pwd确保你拥有正确的绝对路径。

4. 重启Claude桌面版

保存配置后，重启Claude桌面版以使更改生效。

✨ 主要特性

智能上下文管理

• 高效处理大型文件和文件系统：
  • 部分读取，仅关注相关内容。
  • 精确的上下文控制，可准确找到所需内容。
  • 支持分页的高效令牌搜索结果。
  • 多文件操作，减少请求开销。

智能文件操作

• 支持行定位读取，可配置上下文窗口。
• 高级编辑功能，具备内容验证，防止冲突。
• 细粒度搜索功能，超越标准grep。
• 支持相对行引用，便于精确文件操作。

安全文件访问

仅允许在明确允许的目录内进行操作。

全面操作

• 标准操作（读取、写入、列出、移动、删除）。
• 增强操作（树形可视化、查找重复项等）。
• 集成grep的高级搜索（可用时使用ripgrep）：
  • 上下文控制（如grep的-A/-B/-C选项）。
  • 大结果集的结果分页。
• 支持内容验证和相对行号的行定位操作。

性能优化

• 高效处理大型文件和目录。
• 集成ripgrep，实现快速搜索。
• 行定位操作，避免加载整个文件。

全面测试

采用行为驱动方法，拥有75多个测试用例。

跨平台支持

可在Windows、macOS和Linux上运行。

📦 安装指南

克隆并设置

首先，若尚未安装uv，请进行安装：

# 使用官方安装程序安装uv
curl -fsSL https://raw.githubusercontent.com/astral-sh/uv/main/install.sh | bash

# 或者使用pipx安装
pipx install uv

然后克隆仓库并安装依赖项：

# 克隆仓库
git clone https://github.com/safurrier/mcp-filesystem.git
cd mcp-filesystem

# 使用uv安装依赖项
uv pip sync requirements.txt requirements-dev.txt

💻 使用示例

基础用法

查看服务器日志

你可以在Claude桌面版中监控服务器日志：

# 在macOS上
tail -n 20 -f ~/Library/Logs/Claude/mcp-server-mcp-filesystem.log

# 在Windows（PowerShell）上
Get-Content -Path "$env:APPDATA\Claude\Logs\mcp-server-mcp-filesystem.log" -Tail 20 -Wait

运行服务器

运行服务器并访问特定目录：

# 使用uv（推荐）
uv run run_server.py /path/to/dir1 /path/to/dir2

# 或者使用标准Python
python run_server.py /path/to/dir1 /path/to/dir2

# 实际路径示例
uv run run_server.py /Users/username/Documents /Users/username/Downloads

选项

• --transport 或 -t：传输协议（stdio 或 sse，默认：stdio）
• --port 或 -p：SSE传输端口（默认：8000）
• --debug 或 -d：启用调试日志
• --version 或 -v：显示版本信息

使用MCP检查器

使用MCP检查器进行交互式测试和调试：

# 基本用法
npx @modelcontextprotocol/inspector uv run run_server.py /path/to/directory

# 使用SSE传输
npx @modelcontextprotocol/inspector uv run run_server.py /path/to/directory --transport sse --port 8080

# 输出调试信息
npx @modelcontextprotocol/inspector uv run run_server.py /path/to/directory --debug

高级用法

读取文件行

Tool: read_file_lines
Arguments: {
  "path": "/path/to/file.txt",
  "offset": 99,        # 基于0的索引（第100行）
  "limit": 51,         # 读取51行
  "encoding": "utf-8"  # 可选编码
}

使用grep搜索内容

Tool: grep_files
Arguments: {
  "path": "/path/to/search",
  "pattern": "function\\s+\\w+\\(",
  "is_regex": true,
  "context_before": 2,       # 显示每个匹配项前的2行（如grep的 -A 选项）
  "context_after": 5,        # 显示每个匹配项后的5行（如grep的 -B 选项）
  "include_patterns": ["*.js", "*.ts"],
  "results_offset": 0,       # 从第一个匹配项开始
  "results_limit": 20        # 最多显示20个匹配项
}

行定位编辑

Tool: edit_file_at_line
Arguments: {
  "path": "/path/to/file.txt",
  "line_edits": [
    {
      "line_number": 15,
      "action": "replace",
      "content": "This is the new content for line 15\n",
      "expected_content": "Original content of line 15\n" # 编辑前验证内容
    },
    {
      "line_number": 20,
      "action": "delete"
    }
  ],
  "offset": 0,                           # 从该偏移量开始考虑行
  "relative_line_numbers": false,        # 行号是否相对于偏移量
  "abort_on_verification_failure": true, # 验证失败时停止
  "dry_run": true                        # 预览更改而不应用
}

查找重复文件

Tool: find_duplicate_files
Arguments: {
  "path": "/path/to/search",
  "recursive": true,
  "min_size": 1024,
  "format": "text"
}

📚 详细文档

可用工具

基本文件操作

• read_file：读取文件的完整内容。
• read_multiple_files：同时读取多个文件。
• write_file：创建新文件或覆盖现有文件。
• create_directory：创建新目录或确保目录存在。
• list_directory：获取文件和目录的详细列表。
• move_file：移动或重命名文件和目录。
• get_file_info：检索文件或目录的详细元数据。
• list_allowed_directories：列出服务器允许访问的目录。

行定位操作

• read_file_lines：使用偏移量/限制参数读取特定行范围。
• edit_file_at_line：具备内容验证和相对行号的精确编辑：
  • 支持内容验证，防止编辑过时内容。
  • 支持相对行号，便于区域编辑。
  • 支持多种编辑操作（替换、插入前、插入后、删除）。
• head_file：读取文本文件的前N行。
• tail_file：读取文本文件的后N行。

高级搜索

• grep_files：在文件中搜索模式，具备强大选项：
  • 集成ripgrep以提高性能（有Python后备方案）。
  • 细粒度上下文控制（如grep的-A/-B/-C选项）。
  • 大搜索结果的结果分页。
  • 支持正则表达式，可设置大小写敏感和全字匹配选项。
• search_files：搜索匹配模式的文件，支持内容搜索。
• directory_tree：获取文件和目录的递归树视图。

分析和报告

• calculate_directory_size：计算目录的总大小。
• find_duplicate_files：通过比较内容查找重复文件。
• compare_files：比较两个文本文件并显示差异。
• find_large_files：查找大于指定大小的文件。
• find_empty_directories：查找空目录。

处理大型文件和文件系统的高效工作流程

智能上下文发现

• 使用grep_files，通过精确的上下文控制找到所需内容。
• 对匹配项前后的上下文行进行细粒度控制，避免令牌浪费。
• 高效分页处理大结果集，避免超出令牌限制。
• 集成ripgrep，可处理包含数百万个文件和行的大型文件系统。

目标读取

• 使用read_file_lines，通过偏移量/限制仅检查相关部分。
• 基于0的索引，使用简单的偏移量/限制参数精确检索内容。
• 精确控制读取的行数，提高令牌效率。
• 同时读取多个文件，减少往返次数。

精确编辑

• 使用edit_file_at_line进行目标编辑，具备内容验证。
• 编辑前验证内容未更改，防止冲突。
• 使用相对行号进行复杂文件的区域编辑。
• 一次操作支持多种编辑操作，处理复杂更改。
• 支持预运行功能，预览更改后再应用。

高级分析

• 使用find_duplicate_files和compare_files等专业工具。
• 使用directory_tree生成目录树，便于快速导航。
• 使用find_large_files和find_empty_directories识别问题区域。

与标准文件系统MCP服务器相比的优势

令牌效率

• 智能行定位操作避免将整个文件加载到上下文中。
• 大结果集的分页控制，防止上下文溢出。
• 精确的grep，支持上下文控制（不仅是全文件搜索）。
• 多文件读取减少往返请求。

智能编辑

• 内容验证，防止编辑冲突。
• 行定位编辑，无需加载整个文件。
• 支持相对行号，便于区域编辑。
• 支持预运行功能，预览更改后再应用。

高级搜索

• 集成ripgrep，提高大型文件系统性能。
• 支持上下文感知结果（不仅是匹配项）。
• 对返回内容进行细粒度控制。
• 基于模式的文件查找，支持排除选项。

附加实用工具

• 文件比较和去重。
• 目录大小计算和分析。
• 空目录识别。
• 基于树的目录可视化。

安全重点

• 强大的路径验证和沙箱机制。
• 防止路径遍历攻击。
• 符号链接验证和安全保护。
• 详细的错误报告，不暴露敏感信息。

已知问题和限制

• 路径解析：为获得最一致的结果，请始终使用绝对路径。相对路径可能相对于服务器的工作目录而非允许的目录进行解释。
• 性能：对于大型目录，find_duplicate_files等操作或递归搜索可能需要较长时间才能完成。
• 权限处理：服务器以运行它的用户的相同权限运行。请确保服务器对需要访问的目录具有适当的权限。

安全

服务器实施严格的路径验证，防止访问允许目录之外的内容：

• 仅允许在明确允许的目录内进行操作。
• 防止路径遍历攻击。
• 验证符号链接，确保其不指向允许目录之外。
• 返回有意义的错误消息，不暴露敏感信息。

性能考虑

为获得最佳grep功能性能：

• 安装ripgrep (rg)。
• 服务器在可用时会自动使用ripgrep，并提供Python后备方案。

🔧 技术细节

该服务器使用FastMCP SDK构建，以更好地符合当前MCP最佳实践。它采用高效的组件缓存系统和直接装饰器模式。

📄 许可证

MIT许可证