MCP 파일 시스템 서버

대용량 파일 및 파일 시스템과의 지능적인 상호작용에 최적화된 파일 시스템 운영을 위한 강력한 모델 컨텍스트 프로토콜(MCP) 서버입니다. 스마트한 컨텍스트 관리를 통해 파일 및 디렉터리에 대한 안전한 액세스를 제공하여 방대한 데이터 작업 시 효율성을 극대화합니다.

왜 MCP 파일 시스템을 선택해야 할까요?

스마트 컨텍스트 관리 : 대용량 파일 및 파일 시스템을 효율적으로 작업합니다.
- 관련 내용에만 집중하기 위한 부분적 읽기
- 필요한 것을 정확히 찾을 수 있는 정확한 컨텍스트 제어
- 페이지 분할을 통한 토큰 효율적 검색 결과
- 요청 오버헤드를 줄이기 위한 다중 파일 작업
지능형 파일 작업 :
- 구성 가능한 컨텍스트 창을 통한 라인 대상 읽기
- 충돌을 방지하기 위한 콘텐츠 검증을 통한 고급 편집
- 표준 grep을 능가하는 세분화된 검색 기능
- 정확한 파일 조작을 위한 상대적 줄 참조

주요 특징

보안 파일 액세스 : 명시적으로 허용된 디렉토리 내에서만 작업을 허용합니다.
종합적인 운영 : 전체 파일 시스템 기능 세트
- 표준 작업(읽기, 쓰기, 나열, 이동, 삭제)
- 향상된 작업(트리 시각화, 중복 찾기 등)
- grep 통합을 통한 고급 검색(사용 가능한 경우 ripgrep 사용)
  - 컨텍스트 제어(grep의 -A/-B/-C 옵션과 유사)
  - 대규모 결과 집합에 대한 결과 페이지 매김
- 콘텐츠 검증 및 상대 줄 번호를 사용한 줄별 타겟팅 작업
성능 최적화 :
- 대용량 파일과 디렉토리를 효율적으로 처리합니다
- 매우 빠른 검색을 위한 Ripgrep 통합
- 전체 파일 로드를 방지하기 위한 라인 대상 작업
종합 테스트 : 행동 중심 접근 방식을 적용한 75개 이상의 테스트
크로스 플랫폼 : Windows, macOS 및 Linux에서 작동합니다.

빠른 시작 가이드

1. 복제 및 설정

먼저, 아직 uv를 설치하지 않았다면 설치하세요.

지엑스피1

그런 다음 저장소를 복제하고 종속성을 설치합니다.

# 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 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에서 서버 로그를 모니터링할 수 있는 방법은 다음과 같습니다.

# 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

이 기능은 문제를 디버깅하거나 클로드가 정확히 무엇을 요청하는지 확인하는 데 특히 유용합니다.

서버 실행

특정 디렉토리에 접근하여 서버를 실행합니다.

# 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

이 서버는 최신 MCP 모범 사례에 더욱 부합하도록 FastMCP SDK를 기반으로 구축되었습니다. 효율적인 컴포넌트 캐싱 시스템과 직접 데코레이터 패턴을 사용합니다.

Claude 데스크톱 통합

MCP-Filesystem을 통합하려면 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",
        "/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 : 파일 및 디렉토리의 재귀적 트리 뷰를 가져옵니다.

분석 및 보고

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 사용하면 정확한 컨텍스트 제어로 필요한 것을 정확하게 찾을 수 있습니다.
- 일치 전후 컨텍스트 줄에 대한 세밀한 제어로 토큰 낭비를 방지합니다.
- 과도한 토큰 제한 없이 효율적으로 대규모 결과 세트를 페이지별로 분할합니다.
- Ripgrep 통합은 수백만 개의 파일과 줄이 있는 대규모 파일 시스템을 처리합니다.
타겟 독서
- offset/limit을 사용하여 read_file_lines 가 있는 관련 섹션만 검사합니다.
- 정확한 콘텐츠 검색을 위한 간단한 오프셋/제한 매개변수를 사용한 0 기반 인덱싱
- 토큰 효율성을 극대화하기 위해 정확히 몇 줄을 읽어야 하는지 제어합니다.
- 왕복 시간을 줄이기 위해 여러 파일을 동시에 읽습니다.
정확한 편집
- 콘텐츠 검증을 통해 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 ) 설치
서버는 Python 대체 수단과 함께 사용 가능한 경우 ripgrep을 자동으로 사용합니다.

특허

MIT 라이센스

Integrations