MCP 服务器

MCP Filesystem Server

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

README

MCP 文件系统服务器

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

为什么选择 MCP-Filesystem？

智能上下文管理：高效处理大型文件和文件系统
- 部分读取，仅关注相关内容
- 精确的上下文控制，可准确找到所需内容
- 具有分页功能的 Token 高效搜索结果
- 多文件操作，减少请求开销
智能文件操作：
- 具有可配置上下文窗口的行定向读取
- 具有内容验证的高级编辑，可防止冲突
- 超出标准 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 "Repository path: $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",
        "/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 监视服务器日志：

# 在 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 /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 Inspector 一起使用

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

# 基本用法
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

此服务器已使用 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",
        "/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 替换为您在系统上克隆存储库的实际路径。

开发

运行测试

# 运行所有测试
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：读取具有 offset/limit 参数的特定行范围
edit_file_at_line：使用内容验证和相对行号进行精确编辑
- 支持内容验证以防止编辑过时的内容
- 相对行号，便于区域编辑
- 多个编辑操作（replace、insert_before、insert_after、delete）
head_file：读取文本文件的前 N 行
tail_file：读取文本文件的最后 N 行

高级搜索

grep_files：使用强大的选项在文件中搜索模式
- Ripgrep 集成以提高性能（带有 Python 回退）
- 精细的上下文控制（如 grep 的 -A/-B/-C 选项）
- 用于大型搜索结果的结果分页
- 具有区分大小写和全字选项的 RegEx 支持
search_files：搜索与内容搜索模式匹配的文件
directory_tree：获取文件和目录的递归树视图

分析和报告

calculate_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 通过精确的上下文控制准确找到您需要的内容
- 对匹配项之前/之后的上下文行进行细粒度控制，防止 Token 浪费
- 高效地分页浏览大型结果集，而不会超出 Token 限制
- Ripgrep 集成可处理包含数百万个文件和行的大型文件系统
定向读取
- 仅使用带有 offset/limit 的 read_file_lines 检查相关部分
- 具有简单 offset/limit 参数的从零开始的索引，用于精确的内容检索
- 精确控制要读取的行数，以最大限度地提高 Token 效率
- 同时读取多个文件以减少往返次数
精确编辑
- 使用带有内容验证的 edit_file_at_line 进行定向编辑
- 在编辑之前验证内容是否已更改，以防止冲突
- 使用相对行号在复杂文件中进行区域编辑
- 在单个操作中进行多个编辑操作以进行复杂更改
- 具有 Dry-run 功能，可在应用之前预览更改
高级分析
- 使用 find_duplicate_files 和 compare_files 等专用工具
- 使用 directory_tree 生成目录树以进行快速导航
- 使用 find_large_files 和 find_empty_directories 识别有问题的地方

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

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

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

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

已知问题和限制

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

安全

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

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

性能注意事项

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

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

许可证

MIT License