mcp文件系统

Name: mcp文件系统
Author: safurrier

作者：safurrier51 星标更新：2025-03-07

安装使用来源：spider==github.com

项目介绍

MCP 文件系统服务器

一个强大的模型上下文协议（MCP）服务器，用于优化与大型文件和文件系统的智能交互。它提供安全访问文件和目录的功能，并通过智能上下文管理来提高处理大量数据时的效率。

为什么选择 MCP-Filesystem？

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

主要特性

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

快速入门指南

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 Desktop

打开你的 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",
        "/绝对路径到/mcp-filesystem",
        "run",
        "run_server.py",
        "/绝对路径到/dir1",
        "/绝对路径到/dir2"
      ]
    }
  }
}

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

4. 重启 Claude Desktop

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

安装

使用

监控服务器日志

你可以从 Claude Desktop 监控服务器日志：

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

这对于调试问题或查看 Claude 正在请求的具体内容特别有用。

运行服务器

使用特定目录访问权限运行服务器：

# 使用 uv（推荐）
uv run run_server.py /路径到/dir1 /路径到/dir2

# 或使用标准 Python
python run_server.py /路径到/dir1 /路径到/dir2

# 示例使用实际路径
uv run run_server.py /Users/用户名/Documents /Users/用户名/Downloads

选项

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

使用 MCP Inspector

对于交互式测试和调试：

# 基本用法
npx @modelcontextprotocol/inspector uv run run_server.py /路径到/目录

# 使用 SSE 传输
npx @modelcontextprotocol/inspector uv run run_server.py /路径到/目录 --transport sse --port 8080

# 使用调试输出
npx @modelcontextprotocol/inspector uv run run_server.py /路径到/目录 --debug

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

Claude Desktop 集成

编辑你的 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",
        "/路径到/mcp-filesystem/仓库",
        "run",
        "run_server.py"
      ]
    }
  }
}

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

{
  "mcpServers": {
    "mcp-filesystem": {
      "command": "uv",
      "args": [
        "--directory",
        "/路径到/mcp-filesystem/仓库",
        "run",
        "run_server.py",
        "/Users/你的用户名/项目",
        "/Users/你的用户名/Documents"
      ]
    }
  }
}

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

开发

运行测试

# 运行所有测试
uv run -m pytest tests/

# 运行特定测试文件
uv run -m pytest tests/test_operations_unit.py

# 运行带有覆盖率
uv run -m pytest tests/ --cov=mcp_filesystem --cov-report=term-missing

代码风格和质量

# 格式化代码
uv run -m ruff format mcp_filesystem

# 检查代码
uv run -m ruff check --fix mcp_filesystem

# 类型检查
uv run -m mypy mcp_filesystem

# 运行所有检查
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 选项）
- 对于大量搜索结果的结果分页
- 支持正则表达式，包括大小写敏感和全词选项
search_files：根据模式匹配搜索文件
directory_tree：获取文件和目录的递归树视图

分析和报告

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

使用示例

读取文件行

工具：read_file_lines
参数：{
  "path": "/路径到/file.txt",
  "offset": 99,        # 0 基础索引（第 100 行）
  "limit": 51,         # 读取 51 行
  "encoding": "utf-8"  # 可选编码
}

使用 grep 搜索内容

工具：grep_files
参数：{
  "path": "/路径到/search",
  "pattern": "function\\s+\\w+\\(",
  "is_regex": true,
  "context_before": 2,       # 显示每个匹配前的 2 行（类似 grep -B）
  "context_after":  5,       # 显示每个匹配后的 5 行（类似 grep -A）
  "include_patterns": ["*.js", "*.ts"],
  "results_offset": 0,       # 从第一个匹配开始
  "results_limit": 20        # 显示最多 20 个匹配
}

行目标编辑

工具：edit_file_at_line
参数：{
  "path": "/路径到/file.txt",
  "line_edits": [
    {
      "line_number": 15,
      "action": "replace",
      "content": "这是第 15 行的新内容\n",
      "expected_content": "第 15 行的原始内容\n" # 编辑前验证内容
    },
    {
      "line_number": 20,
      "action": "delete"
    }
  ],
  "offset": 0,                           # 从此偏移量开始考虑行
  "relative_line_numbers": false,        # 是否行号相对于偏移量
  "abort_on_verification_failure": true, # 验证失败时停止
  "dry_run": true                        # 预览更改而不应用
}

查找重复文件

工具：find_duplicate_files
参数：{
  "path": "/路径到/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 或递归搜索可能需要相当长的时间才能完成。
权限处理：服务器以运行它的用户相同的权限运行。确保服务器具有访问所需目录的适当权限。

安全性

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

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

性能考虑

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

安装 ripgrep (rg)
如果可用，服务器会自动使用 ripgrep，否则使用 Python 回退

许可证

MIT 许可证