MCP 文件系统服务器

强大的模型上下文协议 (MCP) 服务器，用于文件系统操作，并针对与大型文件和文件系统的智能交互进行了优化。它通过智能上下文管理提供对文件和目录的安全访问，从而在处理海量数据时最大限度地提高效率。

为什么选择 MCP-Filesystem？

智能上下文管理：高效处理大型文件和文件系统
- 部分阅读，只关注相关内容
- 精确的上下文控制，帮您找到所需内容
- 具有分页功能的高效搜索结果
- 多文件操作以减少请求开销
智能文件操作：
- 使用可配置上下文窗口进行行定向阅读
- 具有内容验证的高级编辑可防止冲突
- 超越标准 grep 的细粒度搜索功能
- 用于精确文件操作的相对行引用

主要特点

安全文件访问：仅允许在明确允许的目录内进行操作
全面的操作：全套文件系统功能
- 标准操作（读取、写入、列出、移动、删除）
- 增强操作（树可视化、重复查找等）
- 使用 grep 集成进行高级搜索（可用时使用 ripgrep）
  - 上下文控制（如 grep 的 -A/-B/-C 选项）
  - 大型结果集的结果分页
- 具有内容验证和相对行号的针对行的操作
性能优化：
- 高效处理大型文件和目录
- Ripgrep 集成，实现极快的搜索速度
- 针对行的操作以避免加载整个文件
全面测试：超过 75 项采用行为驱动方法的测试
跨平台：适用于 Windows、macOS 和 Linux

快速入门指南

1. 克隆和设置

首先，如果尚未安装 uv，请安装它：

# Install uv using the official installer
curl -fsSL https://raw.githubusercontent.com/astral-sh/uv/main/install.sh | bash

# Or with pipx
pipx install uv

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

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

# Install dependencies with uv
uv pip sync requirements.txt requirements-dev.txt

2. 获取绝对路径

您需要存储库位置和要访问的任何目录的绝对路径：

# Get the absolute path to the repository
REPO_PATH=$(pwd)
echo "Repository path: $REPO_PATH"

# Get absolute paths to directories you want to access
realpath ~/Documents
realpath ~/Downloads
# Or on systems without realpath:
echo "$(cd ~/Documents && pwd)"

3.配置Claude桌面

打开您的 Claude Desktop 配置文件：

在 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 Desktop

保存配置后，重新启动 Claude Desktop 以使更改生效。

安装

用法

查看服务器日志

您可以使用以下方式从 Claude Desktop 监控服务器日志：

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

# On Windows (PowerShell)
Get-Content -Path "$env:APPDATA\Claude\Logs\mcp-server-mcp-filesystem.log" -Tail 20 -Wait

这对于调试问题或准确了解 Claude 的要求特别有用。

运行服务器

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

# Using uv (recommended)
uv run run_server.py /path/to/dir1 /path/to/dir2

# Or using standard Python
python run_server.py /path/to/dir1 /path/to/dir2

# Example with actual paths
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 Inspector 一起使用

使用 MCP Inspector 进行交互式测试和调试：

# Basic usage
npx @modelcontextprotocol/inspector uv run run_server.py /path/to/directory

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

# With debug output
npx @modelcontextprotocol/inspector uv run run_server.py /path/to/directory --debug

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

Claude 桌面集成

编辑您的 Claude Desktop 配置文件以集成 MCP-Filesystem：

配置文件位置：

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

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

要允许访问特定目录，请将它们添加为附加参数：

{
  "mcpServers": {
    "mcp-filesystem": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-filesystem/repo",
        "run",
        "run_server.py",
        "/Users/yourusername/Projects",
        "/Users/yourusername/Documents"
      ]
    }
  }
}

注意： --directory标志很重要，因为它告诉 uv 在哪里找到包含 run_server.py 的存储库。请将/path/to/mcp-filesystem/repo替换为您在系统上克隆存储库的实际路径。

发展

运行测试

# Run all tests
uv run -m pytest tests/

# Run specific test file
uv run -m pytest tests/test_operations_unit.py

# Run with coverage
uv run -m pytest tests/ --cov=mcp_filesystem --cov-report=term-missing

代码风格和质量

# Format code
uv run -m ruff format mcp_filesystem

# Lint code
uv run -m ruff check --fix mcp_filesystem

# Type check
uv run -m mypy mcp_filesystem

# Run all checks
uv run -m ruff format mcp_filesystem && \
uv run -m ruff check --fix mcp_filesystem && \
uv run -m mypy mcp_filesystem && \
uv run -m pytest tests --cov=mcp_filesystem

可用工具

基本文件操作

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 选项）
- 大型搜索结果的分页
- RegEx 支持区分大小写和全字选项
search_files ：使用内容搜索来搜索匹配模式的文件
directory_tree ：获取文件和目录的递归树视图

分析和报告

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

使用示例

读取文件行

Tool: read_file_lines
Arguments: {
  "path": "/path/to/file.txt",
  "offset": 99,        # 0-based indexing (line 100)
  "limit": 51,         # Read 51 lines
  "encoding": "utf-8"  # Optional encoding
}

使用 Grep 搜索内容

Tool: grep_files
Arguments: {
  "path": "/path/to/search",
  "pattern": "function\\s+\\w+\\(",
  "is_regex": true,
  "context_before": 2,       # Show 2 lines before each match (like grep -B)
  "context_after": 5,        # Show 5 lines after each match (like grep -A)
  "include_patterns": ["*.js", "*.ts"],
  "results_offset": 0,       # Start from the first match
  "results_limit": 20        # Show at most 20 matches
}

行目标编辑

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" # Verify content before editing
    },
    {
      "line_number": 20,
      "action": "delete"
    }
  ],
  "offset": 0,                           # Start considering lines from this offset
  "relative_line_numbers": false,        # Whether line numbers are relative to offset
  "abort_on_verification_failure": true, # Stop on verification failure
  "dry_run": true                        # Preview changes without applying
}

查找重复文件

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

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

MCP-Filesystem 专为与大文件和复杂文件系统进行智能交互而设计：

智能上下文发现
- 使用grep_files通过精确的上下文控制准确找到您需要的内容
- 对匹配之前/之后的上下文行进行细粒度控制可防止令牌浪费
- 高效地对大量结果集进行分页，不受令牌限制
- Ripgrep 集成可处理包含数百万个文件和行的大型文件系统
有针对性的阅读
- 使用偏移量/限制仅检查与read_file_lines相关的部分
- 使用简单的偏移/限制参数进行零基索引，以实现精确的内容检索
- 精确控制读取的行数以最大化令牌效率
- 同时读取多个文件以减少往返
精准编辑
- 使用edit_file_at_line进行有针对性的编辑并进行内容验证
- 编辑前请确认内容未发生改变，以防止发生冲突
- 使用相对行号进行复杂文件中的区域编辑
- 单个操作中的多个编辑操作可实现复杂的更改
- 在应用之前预览更改的试运行功能
高级分析
- 使用find_duplicate_files和compare_files等专用工具
- 使用directory_tree生成目录树以便快速导航
- 使用find_large_files和find_empty_directories识别问题区域

此工作流程对于需要处理大型文件和文件系统的 AI 工具尤其有用。例如，Claude 和其他高级 AI 助手可以利用这些功能高效地导航代码库、分析日志文件或处理任何大型文本数据集，同时保持令牌效率。

相较于标准文件系统 MCP 服务器的优势

与基本文件系统 MCP 服务器不同，MCP-Filesystem 提供：

代币效率
- 智能行目标操作避免将整个文件加载到上下文中
- 大量结果的分页控制可防止上下文溢出
- 使用上下文控制进行精确的 grep（不仅仅是整个文件搜索）
- 多文件读取减少往返请求
智能编辑
- 内容验证以防止编辑冲突
- 不需要整个文件的行目标编辑
- 支持相对行号，更易于区域编辑
- 在应用之前预览更改的试运行功能
高级搜索
- Ripgrep 集成以实现大规模文件系统性能
- 上下文感知结果（不仅仅是匹配）
- 对返回内容进行细粒度控制
- 基于模式的文件查找并支持排除
附加实用程序
- 文件比较和重复数据删除
- 目录大小计算与分析
- 空目录识别
- 基于树的目录可视化
安全焦点
- 强大的路径验证和沙盒
- 防止路径遍历攻击
- 符号链接验证和安全
- 详细的错误报告，不暴露敏感信息

已知问题和限制

路径解析：始终使用绝对路径以获得最一致的结果。相对路径可能会被解释为相对于服务器的工作目录，而不是允许的目录。
性能：对于大型目录，诸如find_duplicate_files或 recusrive search 之类的操作可能需要很长时间才能完成。
权限处理：服务器的运行权限与运行它的用户相同。确保服务器对其需要访问的目录具有适当的权限。

安全

服务器强制执行严格的路径验证，以防止访问允许的目录之外的目录：

仅允许在明确允许的目录内进行操作
提供针对路径遍历攻击的保护
验证符号链接以确保它们不指向允许的目录之外
返回有意义的错误消息而不暴露敏感信息

性能考虑

为了获得 grep 功能的最佳性能：

安装ripgrep （ rg ）
如果可用，服务器会自动使用 ripgrep，并使用 Python 回退

执照

MIT 许可证

MCP Filesystem Server

Integrations