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 许可证

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

local-only server

The server can only run on the client's local machine because it depends on local resources.

模型上下文协议服务器提供与文件和文件系统的安全、智能交互，为处理大型文件和复杂目录结构提供智能上下文管理和高效的令牌操作。

Related MCP Servers

Filesystem MCP Server
bsmi021
-
security
A
license
-
quality
A Model Context Protocol server that provides file system operations, analysis, and manipulation capabilities through a standardized tool interface.
Last updated -
1
TypeScript
MIT License
Nash MCP Server
nash-app
-
security
A
license
-
quality
A Model Context Protocol server that enables seamless execution of commands, Python code, web content fetching, and reusable task management with secure credentials handling.
Last updated -
2
Python
MIT License
File Operations MCP Server
bsmi021
A
security
A
license
A
quality
A Model Context Protocol server that enables enhanced file system operations including reading, writing, copying, moving files with streaming capabilities, directory management, file watching, and change tracking.
Last updated -
12
6
TypeScript
MIT License
MCP Filesystem Server
gabrielmaialva33
-
security
A
license
-
quality
A secure Model Context Protocol server that provides controlled filesystem access within predefined directories, enabling AI models to perform file and directory operations with strict path validation.
Last updated -
40
7
TypeScript
MIT License

View all related MCP servers